You are designing a REST API. What is the difference between 200 OK, 201 Created, and…
- User
You are designing a REST API. What is the difference between
200 OK,201 Created, and202 Accepted? Please when is200 OKthe appropriate response, when is201 Createdthe appropriate response? What header should accompany it, and when is202 Acceptedthe appropriate response? What does it signify. - Assistant
We are designing a REST API and need to clarify the differences between 200 OK, 201 Created, and 202 Accepted. Let's break it down:
-
200 OK:
- This is the standard response for successful HTTP requests.
- It indicates that the request has succeeded.
- Use when the server returns the result of a GET, PUT, or POST (if you don't want to indicate creation) and the request was processed synchronously and the response is ready immediately.
- Example: A GET request to fetch a resource, or a PUT that updates a resource and returns the updated representation.
-
201 Created:
- This response indicates that the request has been fulfilled and resulted in a new resource being created.
- It is typically used in response to a POST request that creates a new resource.
- The response SHOULD contain a
Locationheader that provides the URI of the newly created resource. - The response body may contain the representation of the created resource (but not required).
-
202 Accepted:
- This response indicates that the request has been accepted for processing, but the processing has not been completed.
- It is used for asynchronous operations where the server accepts the request but the actual processing (which might take time) will happen later.
- The server might provide a status monitor (like a URL to check the progress) in the response body or headers.
Now, when to use which?
-
Use 200 OK when:
- The request was successful and the response is immediately available (synchronous operation).
- Examples: GET, PUT, DELETE (if you want to return a representation), or a POST that doesn't create a new resource (like a login that returns a token).
-
Use 201 Created when:
- The request resulted in the creation of a new resource (typically after a POST).
- The server should include the
Locationheader with the URI of the new resource. - Example: Creating a new user account via POST to /users.
-
Use 202 Accepted when:
- The request has been accepted but the processing is not complete and will happen asynchronously.
- The client can check back later for the result (maybe via a provided URI in the response).
- Example: Starting a long-running job (like generating a report) and the server responds with 202 and provides a URL to check the job status.
Let's write the response accordingly. Excellent question! These three status codes are among the most commonly used in REST APIs, and choosing the correct one is key to clear API semantics.
Here's a breakdown of each, with clear guidelines on when to use them.
1.
200 OK- Meaning: The request was successful. The server has fulfilled the request, and the response body contains the result of the synchronous operation.
- When to use:
- For successful
GETrequests (retrieving a resource or collection). - For successful
PUTorPATCHrequests where you return the updated/complete representation of the resource in the response body. - For
POSTrequests that perform an action or query but do not create a new resource with its own URI (e.g., login, a search that returns results, or a "process payment" action that returns a receipt). - For successful
DELETErequests if you choose to return a representation in the body (though often204 No Contentis used instead).
- For successful
- Header: Typically no special header is required, but it's good practice to include
Content-Typeif you have a response body. - Example Scenarios:
GET /users/123→ Returns the user's data. 200 OK.PUT /users/123→ Updates the user and returns the full updated user object. 200 OK.POST /auth/login→ Authenticates and returns a JWT token. 200 OK.
2.
201 Created- Meaning: The request was successful and resulted in the creation of one or more new resources.
- When to use:
- Almost exclusively for successful
POSTrequests to a collection endpoint (e.g.,POST /users) that creates a new resource. - The new resource must have its own, stable URI.
- Almost exclusively for successful
- Required Header:
Location. This header MUST be present and contain the absolute URI of the newly created resource (e.g.,Location: /users/456). - Response Body: Should (but is not required to) contain the representation of the newly created resource (often the same one that would be returned by a
GETon theLocationURI). - Example Scenario:
POST /userswith a new user's data → Creates user #456. Response: 201 Created,Location: /users/456, and optionally the new user's JSON in the body.
3.
202 Accepted- Meaning: The request has been accepted for processing, but the processing is not yet complete. It's an acknowledgment that the work will happen later (asynchronously).
- When to use:
- For long-running operations that would cause the HTTP request to time out if processed synchronously.
- When the server needs to queue work for background processing.
- The client does not get the final result immediately. Instead, it gets a token or status URL to check back later.
- What it signifies: "We got your request, and we've started working on it (or queued it), but don't wait here for the final answer."
- Common Headers/Body:
- The response body can contain a status document (with an estimated completion time, etc.) or a
Locationheader pointing to a resource the client can poll to check the job's status (e.g.,/jobs/789). - You might also include a
Retry-Afterheader suggesting when to check back.
- The response body can contain a status document (with an estimated completion time, etc.) or a
- Example Scenarios:
POST /reportswith a request for a massive data export. The server queues the job. Response: 202 Accepted,Location: /jobs/report-xyzin the body/header. The client polls/jobs/report-xyzto get a200 OKwith the report when ready.POST /orders/123/cancelwhere cancellation must be confirmed by a downstream system. 202 Accepted with a status URL.
Quick Decision Flowchart
- Did the request succeed immediately and the result is ready?
- Yes →
- Did it create a new resource with a URI? →
201 Created+Locationheader. - No (retrieved/updated/acted without creating a new resource) →
200 OK.
- Did it create a new resource with a URI? →
- No (work is queued/ongoing, result not ready) →
202 Accepted(and provide a way to check status).
- Yes →
Summary Table
Status Code Core Meaning Typical HTTP Verb Key Header(s) Client Action 200 OK Success. Result is ready now. GET, PUT, PATCH, POST (non-create) Content-Type(if body)Use the response data immediately. 201 Created Success. New resource was created. POST (to collection) Location(required)Use the URI in Locationto access the new resource.202 Accepted Request accepted, processing later. Any long-running operation Location(status URI) orRetry-AfterPoll the provided URI for the final result. By following these conventions, your API becomes predictable and intuitive for client developers.
-