Http methods for RESTful services

Upasana | October 01, 2020 | 6 min read | 3,619 views


Most commonly used HTTP methods are GET, POST, PUT, PATCH and DELETE.

We will cover all of these one by one in detail.

HTTP POST

This method is used to Create new resources on server. normally Http 201 (Created) response is returned by server along with the ID of the newly created resource. Server may return 409 (Conflict), if the resource already exists or 404 (Not found). example:

Request URL
POST /customers
Request Body
{
 "name": "carvia",
 "email": "carvia.tech@mail.com"
}
Response Body
{
 "id": "jgghg-82hgh-jhgjg-3434gf"
}
Status Codes for HTTP POST
Status Code Description

201: Created

Resource is successfully created on server and response contains an entity which describes the status of the request. Response should not be empty in this case.

204: No Content

Action performed by POST method did not result in a resource that can be identified by a URI. HTTP 200 (OK) is also appropriate response in this case.

400: BAD Request

Indicates that client request had some problem, which must be resolved on client side.

HTTP GET

This method is used to Read resource from server and not change it. Server returns Http 200 (OK) if resource is found, 404 (Not Found) if id is not found or 400 (Bad request). It should never modify any resource on server i.e. GET should be idempotent, which means that making multiple identical requests have same effect as calling it exactly once. example:

Request URL
GET /customers/{id}
Response Body
{
 "id": "<uuid>",
 "name": "carvia",
 "email": "carvia.tech@mail.com"
}
Status Codes for HTTP GET
Status Code Description

200: OK

If the resource is found on the server, then it must return HTTP response code 200 (OK) - along with the response body

404: NOT FOUND

Resource is not found on the server.

400: BAD Request

GET request is not correctly formed then server will return HTTP response code 400

HTTP PUT

This method is used to update or replace en existing resource. Server returns 200 (OK) or 204 (No Content), 404 (Not found) if Id not found.

Request
PUT /customers/123
Request Body
{
 "name": "new name",
 "email": "carvia.tech@mail.com"
}

HTTP DELETE

This method is used to delete an existing resource on server. Server returns 405 (Method not allowed) if operation is not supported, 200 (OK) if item is deleted, 404 (not found) if Id is not found or invalid. HTTP spec-wise, DELETE operations are idempotent. If you DELETE a resource, it’s removed. Repeatedly calling DELETE on that resource ends up the same: the resource is gone.

Request
DELETE /customers/123
Status Codes for HTTP DELETE
Status Code Description

200: OK

If the response includes an entity describing the status

202: Accepted

If the delete action has been queued for processing later on

204: No Content

If the delete action has been performed but the response does not include an entity. Http client in this case will not even try to decode the response entity, thus it’s slightly quicker operation.

HTTP PATCH

This method is used to update/modify an existing resource. The PATCH request only needs to contain the changes to the resource, not the complete resource, thus only difference is sent to server instead of complete payload. Server returns 200 (OK) or 404 (Not found) if Id not found.

HTTP Status Codes in RESTful APIs

HTTP defines standard status codes that can be used to convey the results of a client’s request. The status codes are divided into the five categories presented below.

HTTP Status Codes
Status Code Description

1xx: Informational

Communicates transfer protocol-level information.

2xx: Success

Indicates that the client’s request was accepted successfully.

3xx: Redirection

Indicates that the client must take some additional action in order to complete their request.

4xx: Client Error

Indicates that client request had some problem, which must be resolved on client side.

5xx: Server Error

The server takes responsibility for these error status codes.

Detailed error code description from REST perspective

200 (OK)

It is a generic HTTP response that indicates the REST API successfully carried out whatever action the client requested, and that no more specific code in the 2xx series is appropriate.

201 (CREATED)

A REST API responds with the 201 status code whenever a resource is created inside a collection. If the action cannot be carried out immediately, the server SHOULD respond with 202 (Accepted) response instead.

202 (ACCEPTED)

A 202 response is typically used for actions that take a long while to process. It indicates that the request has been accepted for processing, but the processing has not been completed.

204 (No Content)

A 204 response is typically used for actions that does not return any content back to client. Http client does not even try to decode the response body after seeing any 204 status code, thus this operation is faster at HTTP client level.

301 (Moved Permanently)

The 301 status code indicates that the REST API’s resource model has been significantly redesigned and a new permanent URI has been assigned to the client’s requested resource. The REST API should specify the new URI in the response’s Location header and all future requests should be directed to the given URI.

302 (Found)

The HTTP response status code 302 Found is a common way of performing URL redirection. An HTTP response with this status code will additionally provide a URL in the location header field. The user agent (e.g. a web browser) is invited by a response with this code to make a second, otherwise identical, request to the new URL specified in the location field.

304 (Not Modified)

304 is used when the resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match.

400 (Bad Request)

400 is the generic client-side error status, used when no other 4xx error code is appropriate. Errors can be like malformed request syntax, invalid request message parameters, or deceptive request routing etc. The client SHOULD NOT repeat the request without modifications.

401 (Unauthorized)

A 401 error response indicates that the client tried to operate on a protected resource without providing the proper authorization. It may have provided the wrong credentials or none at all. The client MAY repeat the request with a suitable Authorization header field.

403 (Forbidden)

A 403 error response indicates that the client’s request is formed correctly, but the REST API refuses to honor it i.e. the user does not have the necessary permissions for the resource. A 403 response is not a case of insufficient client credentials; that would be 401 (“Unauthorized”). Authentication will not help and the request SHOULD NOT be repeated.

404 (Not Found)

The 404 error status code indicates that the REST API can’t map the client’s URI to a resource but may be available in the future. Subsequent requests by the client are permissible.

405 (Method Not Allowed)

The API responds with a 405 error to indicate that the client tried to use an HTTP method that the resource does not allow. For instance, a read-only resource could support only GET and HEAD, while a controller resource might allow GET and POST, but not PUT or DELETE.

410 (GONE)

The requested content no more exists and the request must not be retried. This condition is expected to be considered permanent. Clients with link editing capabilities SHOULD delete references to the Request-URI after user approval.

415 (Unsupported Media Type)

The 415 error response indicates that the API is not able to process the client’s supplied media type, as indicated by the Content-Type request header.

500 (Internal Server Error)

500 is the generic REST API error response. Most web frameworks automatically respond with this response status code whenever they execute some request handler code that raises an exception.

501 (Not Implemented)

The server either does not recognize the request method, or it lacks the ability to fulfill the request. Usually, this implies future availability (e.g., a new feature of a web-service API). So the request may be retried after some duration.

502 (Bad Gateway)

The server was acting as a gateway or proxy and received an invalid response from the upstream server.

503 (Service Unavailable)

The server cannot handle the request (because it is overloaded or down for maintenance). Generally, this is a temporary state.

504 (Gateway Timeout)

The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.


Top articles in this category:
  1. Rest Assured API Testing Interview Questions
  2. 50 Java Interview Questions for SDET Automation Engineer
  3. Junit interview questions for SDET automation engineer
  4. h2load for REST API benchmarking
  5. What is Idempotent Operation? Which HTTP methods should be made idempotent
  6. HTTP Head request using Java 11 HttpClient - Kotlin
  7. Java Coding Problems for SDET Automation Engineer

Recommended books for interview preparation:

Find more on this topic: