The previous section we went to see what is the RESTful API, and how to build it, along with the commonly used terms in the API. link: https://viblo.asia/p/restful-api-guide-thiet-ke-the-nao-phan-1-jvEla1vdlkw Today we are going to learn about HTTP Methods and formats return of API.

HTTP Methods (Verbs)

HTTP has defined several sets of methods that specify the type of action to be performed on resources. The URL is a sentence in which resources (resources) are nouns and HTTP methods are Verbs (verbs). Important HTTP methods are as follows:

1. The GET method requires data from resources. and do not produce any side effects. For example: / companies / 3 / employees returns a list of all employees from company 3.
2. The POST method requires the server to create resources in the database, mostly when a webform is submitted. For example: / companies / 3 / employees creates a new employee of the company 3. POST is unusual, which means that many requests will have different query ways.
3. The PUT method requires the server to update resources or create resources if it does not exist. For example. / companies / 3 / employees / john will ask the server to update or create if it does not exist, resources john in the company’s staff collection 3. PUT is idempotent, meaning that many requests will have the same result fruit.
4. The DELETE method requires that the resources, or their instances, be deleted from the database. For example: ** / companies / 3 / employees / john / ** will require the server to remove john resources from company 3 employee collection.

There are a few other methods that we will discuss in another article.

HTTP Response Status Codes (status codes)

When the client makes a request to the server via the API, the client knows how to respond, whether it is corrupted, passed or the request is wrong.

HTTP status codes are a series of standardized codes that have different interpretations in different situations. The server must always return the correct status code.

The following are important classifications of HTTP code:

2xx (Success Category)

These status codes indicate that the requested action was successfully received and processed by the server.

• 200 OK – Standard HTTP response represents success for GET, PUT or POST.
• 201 Created – This status code must be returned whenever a new version is created. For example. When creating a new instance, using the POST method, will always return status code 201.
• 204 No Content – Indicates that the request was successfully processed but has not returned any content yet. DELETE may be a good example of this. API DELETE / companies / 43 / employees / 2 will delete employee 2 and in return, we do not need any data in the API response, because we have explicitly requested the system to delete. If there are any errors, such as if employee 2 does not exist in the database, the response code will not belong to the 2xx Success Category but to the 4xx Client Error category .

3xx (Redirection Category)

• 304 Not Modified – Indicates that the client has responded to the buffer. And so there is no need to transfer the same data.

4xx (Client Error Category)

These status codes indicate that the client has issued an error request.

• 400 Bad Request – Indicates that the client request was not processed, because the server cannot understand what the client is requesting.
• 401 Unauthorized – Indicates that the client is not authorized to access the resource and should request again with the required login information.
• 403 Forbidden – Indicates that the request is valid and the client is authenticated, but the client is not allowed to access the page or resources for any reason. For example. Sometimes authorized clients are not allowed to access the directory on the server.
• 404 Not Found – Indicates that the requested resource is not currently available.
• 410 Gone – Indicates that the requested resource is no longer available but was intentionally moved.

5xx (Server Error Category)

• 500 Internal Server Error – Indicates that the request was valid, but the server was completely confused and the server was asked to serve an unexpected condition.
• 503 Service Unavailable – Indicates that the server is down or unavailable for receiving and processing requests. Mostly if the server is under maintenance.

Field Name Casing Convention

We can follow any Casing Convention, but make sure it is appropriate for the application. If the request body or response type is JSON then use camelCase Convention to maintain consistency.

Searching, Sorting, Filtering, and Pagination

All of these actions are simply queries on a data set. There will be no new API set to handle these actions. We need to concatenate query parameters with the GET method API.

Perform these actions with a few examples.

• Sorting – In case the customer wants to receive the list of sorted companies, GET / companies endpoint will accept many sort parameters in the query. For example. GET / companies? Sort = rankasc will sort companies in ascending order.
• Filtering – To filter the data set, we can pass various options through query parameters. For example. GET / companies? Category = banking & location = india will filter corporate listing data with corporate bank directory and location: india.
• Searching – when searching for a company name in the company list, the API endpoint must be GET / companies? Search = Digital Mckinsey .
• Pagination – When a dataset is too large, we divide the dataset into smaller sections, which helps improve performance and makes it easier to handle feedback. For example. ET / companies? Page = 23 means to get a list of companies on page 23.

If adding multiple query parameters in the GET methods causes the URI to be too long, the server can respond with 414 URI Too long HTTP status . In those cases, the params may also be passed into the request body of the POST method.

Versioning

As your APIs are being used by the world, upgrading APIs with some groundbreaking changes will also lead to disruption of existing products or services using your API. http://api.yourservice.com/v1/companies/34/employees is a typical example, with an API version number in the path. If there are any major groundbreaking updates, we can name the new API set v2 or v1.xx

renference: RESTful API Designing Guidelines