BoldHeaderBoldHeader

Understanding RESTful API Response Codes

The topic of "Understanding RESTful API Response Codes" is a crucial aspect of web development and API design. Web services and applications rely on APIs to exchange data, and using appropriate response codes is essential for ensuring that these APIs function correctly and convey their status effectively. These response codes play a pivotal role in maintaining smooth communication between clients and servers, as well as aiding in error handling and issue resolution.

RESTful APIs are built on the HTTP protocol, and they return HTTP status codes as responses to client requests. These status codes carry vital information about the outcome of the request and guide the client on how to proceed. In this article, we will delve into the primary categories of RESTful API response codes and explore what each code signifies in detail.

Reference: https://learn.microsoft.com/ko-kr/azure/architecture/best-practices/api-design

GET Method

  • 200(OK) : Successful retrieval
  • 404(Not Found) : When the requested resource is not found
  • 204(No Content) : When the response has no content, such as no search results or an empty collection.

POST Method

  • 201(Created) : When creating a new resource.
    • The URI of the newly created resource should be included in the Location header of the response (using the generated ID).
  • 200(OK): When the request results in some processing but does not create a new resource. The result is included in the response body.
  • 204(No Content): When there is no response to return.
  • 400(Bad Request): When the client has provided incorrect data. Additional information or URI links regarding the error can be included in the response body.

PUT Method

  • 201(Created): When creating a new resource.
  • 200(OK) or 204(No Content) : When updating an existing resource.
  • 409(Conflict): When the update cannot be performed due to a conflict.

PATCH Method

  • 415(Unsupported Media Type): When an unsupported media type is requested.

  • 400(Bad Request): the request format is incorrect.

  • 409(Conflict): When the request format is correct but the changes cannot be applied.

  • JSON Merge Patch( RFC 7396)

    • Use null values to remove fields.
    • Not suitable for fields that can have null values as they may be interpreted as field deletion.
    • Media Type : application/merge-patch+json

  • JSON Patch(RFC 6902)

    • Specifies the changes to be applied as the operation result.
    • Media Type : application/json-patch+json

DELETE Method

  • 204(No Content): When the deletion is successful.
  • 404(Not Found): When the resource to be deleted is not found.

Asynchronous Operations

For asynchronous operations where the response is sent to the client before the completion of the process:

  • 202(Accepted): The request has been accepted but the operation is not yet complete.

The Location header should include an endpoint URI where the client can check the status.

HTTP/1.1 202 Accepted
Location: /api/status/12345

If the client sends a GET request to this endpoint, the current status should be included in the response. In some cases, the estimated completion time or a cancellation link may be returned.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status":"In progress",
    "link": { "rel":"cancel", "method":"delete", "href":"/api/status/12345" }
}

When creating a new resource during an asynchronous operation, the endpoint should return a 303(See Other) status after the operation is complete, and the Location header of the response should provide the URI of the newly created resource.

HTTP/1.1 303 See Other
Location: /api/orders/12345