Today, as the use of APIs increases, their importance has increased in the same direction. Although APIs seem to carry only data in today’s projects, many processes are carried out on the back side of the API. Such as security of this API, logging of data, different tests. But before starting all these API development processes, did you know that there are accepted steps to design a Web API?
Web API design includes the most important part of developing web services. The created Web APIs can serve API integrations with any mobile, web or other services. Therefore, they must be flexible and as strong as possible. Because the created endpoints can generally be opened to the outside, and later changes here may affect all services and clients or users with dependencies. At first, designing the API design correctly and in the best way makes it easier for the developer and increases the quality.
Let’s examine the steps to be considered when designing Web API step by step.
Table of Contents
HTTP Methods
The http method defines the type of request made for a Web API. HTTP methods such as GET, POST, PUT, PATCH, and DELETE constitute basic CRUD operations.
In addition to these, COPY, PURGE, LINK, UNLINK etc. which are not used very often. There are also methods such as Here are the most commonly used HTTP methods and why they are used:
GET: get data
POST: add new data
PUT: update existing data
PATCH: update only the desired part of the data
DELETE: delete data
Versioning
Failure to use versioning for significant or user/developer changes to the Web APIs in your web service may result in the disruption of existing products or services that use your APIs.
Although there is only one version for now, starting versioning will provide flexibility to application developers against future changes. Versions generally accepted rules start with the letter “v” and include the version number next to it. Your first version may appear as “v1”.
For example, the endpoint created for the product’s resource was created as follows with its first version.
https://xxx.com/v1/products
In this way, the Web API of the product’s resource has been versioned. In any update that will break the data structure, a new Web API can be created with the “v2” version and the operations can be continued with that API.
HTTP Status Codes
In the API mechanism, every request results in a successful or unsuccessful response. HTTP response codes in API responses are responsible for reporting what the result of this request is.
Let’s take a look at the most used and consider the different approaches.
- 200: OK, Operation OK and successful
- 201: Created, New resource successfully created
- 204: No Content, Resource empty/Resource deleted
- 400: Bad Request, Invalid request/Missing or invalid query/parameter
- 401: Unauthorized, Authorization/Authentication required.
- 403: Forbidden, Server denied the request and you do not have permission to request it
- 404: Not found, The requested single resource does not exist
- 405: Method Not Allowed: HTTP method is incorrect
- 409: Conflict: Incompatible request, old version request, or when trying to rebuild an already existing resource.(Already exist)
- 429: Too many requests, Too many requests have been made.
- 415: Unsupported Media Type: Unsupported or incorrect Content-Type
- 5xx contains HTTP response codes consisting of server errors.
When designing a Web API, it is very important that the correct HTTP status codes are set on the code side for each request. Giving correct answers to developers and users who consume the API allows them to correctly guide them about the request they will make.
Searching, sorting, filtering and paging
Keeping the base source URLs as few as possible is one of the best steps to take when designing a Web API. While making a request to the endpoint with the HTTP GET method, you can limit the requested queries and data by adding the query parameters of the collection in the URL.
Sorting: If the teacher wants to get the list of his students in order of student number, the Web API order parameter from which he obtained the list of students should be accepted.
GET /Students?sort=student_number
Filtering: It will make our work easier for the data obtained from the Web API to come according to a certain filter. For example, in the product list from the product resource, we may want only products whose category field is electronic.
GET /Products?category=Electronic
Searching: Although it is highly discouraged to use, in cases where basic filtering is not sufficient for your Web APIs, you can provide the full-text search option. For example, let’s fetch products with Best Quality in the product description in your product resource
GET /Products?Search=Best Quality
Paging: When the dataset is very large, the query is likely to run slowly. With paging, you can divide the dataset into smaller parts, make it performant and manage the response easily. For example, if we want to fetch the 5th page we need, instead of pulling the entire student list (we can talk about thousands or more records here);
GET /Students?page=3
Conclusion
When designing Web APIs, which are important parts of systems, you should think about the future. It is beneficial to design with a flexible, non-changeable and open-to-development approach.
