Create request with POST which response codes 200 or 201 and content

Crafting robust and reliable web applications often hinges on the effective use of HTTP methods, particularly the POST request. When you need to send data to a server to create a new resource, update a record, or submit information, the POST method is your primary tool. Understanding how to properly construct a POST request, and more importantly, interpreting its response codes, specifically the 200 OK or 201 Created status codes, is fundamental for ensuring successful data submission and a smooth user experience. This guide delves into the nuances of creating POST requests with 200 or 201 responses, ensuring your API interactions are both efficient and error-free.

A successful POST operation is not just about sending data; it’s about the server acknowledging receipt, processing the request, and confirming the outcome. Whether the server returns a 200 OK, indicating general success, or a 201 Created, signaling a new resource has been successfully established, these codes are critical for client-side applications to proceed confidently. We’ll explore the best practices for designing your requests and handling the various successful HTTP status codes.

Understanding the POST Method and Its Purpose

The HTTP POST method is designed for submitting an entity to the specified resource, often causing a change in state or side effects on the server. Unlike the GET method, which is idempotent and safe (meaning multiple identical requests have the same effect as a single one and cause no side effects), POST requests are neither. Each POST request typically results in the creation of a new resource or a modification that is not repeatable without consequence.

Common applications of the POST method include submitting a user registration form, uploading a file, or adding a new item to an e-commerce shopping cart. In each of these scenarios, new data is being sent from the client to the server to be stored or processed. The data payload, often in JSON or XML format, is contained within the request body, allowing for complex data structures to be transmitted.

For instance, when a user signs up on a website, their personal details (name, email, password) are encapsulated in a JSON payload and sent via a POST request to the server’s user registration endpoint. The server then processes this data, creates a new user record in its database, and responds with a success status. This clear distinction between data retrieval (GET) and data submission (POST) is a cornerstone of RESTful API design.

Decoding HTTP Status Codes: 200 OK vs. 201 Created

When you send a POST request, the server’s response includes an HTTP status code, which communicates the outcome of the operation. The most desirable success codes are 200 OK and 201 Created, but understanding their specific meanings is crucial for proper client-side logic and API design.

201 Created is the primary success status code for POST requests that result in the creation of a new resource. This code indicates that the request has been fulfilled and has resulted in one or more new resources being created. A typical 201 response will also include a Location header, pointing to the URI of the newly created resource, allowing the client to retrieve or reference it immediately. For example, if you POST a new user object, the 201 response would confirm the user was created and provide the URL to that new user’s profile.

200 OK, while a general success code, is less specific than 201 for resource creation. It signifies that the request has succeeded. While it can be used for POST requests, it’s generally preferred when the POST operation doesn’t explicitly create a new, distinct resource, or perhaps updates an existing one where the exact resource URL isn’t new. For instance, if you’re sending data to trigger a process that doesn’t result in a new tangible resource, or if the POST is idempotent (meaning sending it multiple times has the same effect as sending it once), a 200 OK might be appropriate. However, for true resource creation, 201 Created is the semantically correct and preferred choice, providing clearer communication about the API’s behavior.

For any POST request aiming to create a new resource, the ideal HTTP response code is 201 Created. This status code explicitly confirms that the request has been successfully processed and a new resource has been created on the server. The response should also include a Location header, providing the URI to the newly formed resource, along with a representation of the new resource in the response body, ensuring the client has immediate access to the created entity’s details.

Crafting Effective POST Requests

To successfully create request with POST, which response codes 200 or 201 and content, attention to detail in request construction is paramount. A well-formed POST request ensures the server can correctly interpret and process the data you send.

Structuring the Request Body

The request body (or payload) is where your data resides. For most modern APIs, this will be in JSON format. It’s crucial that the JSON payload adheres to the API’s expected schema. Mismatched data types, missing required fields, or incorrect formatting will lead to server errors, typically a 400 Bad Request.

Consider an example where you want to add a new product to an e-commerce inventory. Your JSON payload might look like this:

{ "name": "Wireless Ergonomic Mouse", "description": "A comfortable mouse designed for long hours of use.", "price": 49.99, "category": "Peripherals", "stock": 150 } 

Ensuring that the keys match the API’s expected fields and the values are of the correct data type (e.g., string for name, number for Question & Answer :

Suppose I write a REST service whose intent is to add a new data item to a system.

I plan to POST to

http://myhost/serviceX/someResources 

Suppose that works, what response code should I use? And what content might I return.

I’m looking at the definitions of HTTP response codes and see these possibilities:

200: Return an entity describing or containing the result of the action;

201: which means CREATED. Meaning *The request has been fulfilled and resulted in a new resource being created. The newly created resource can be referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a Location header field. The response SHOULD include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. *

The latter sounds more in line with the Http spec, but I’m not at all clear what

The response SHOULD include an entity containing a list of resource characteristics and location(s)

means.

Recommendations? Interpretations?

The idea is that the response body gives you a page that links you to the thing:

201 Created

The 201 (Created) status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. The primary resource created by the request is identified by either a Location header field in the response or, if no Location field is received, by the effective request URI.

This means that you would include a Location in the response header that gives the URL of where you can find the newly created thing:

HTTP/1.1 201 Created Date: Sat, 02 Apr 2016 12:22:40 GMT Location: http://stackoverflow.com/a/36373586/12597 

Response body

They then go on to mention what you should include in the response body:

The 201 response payload typically describes and links to the resource(s) created.

For the human using the browser, you give them something they can look at, and click, to get to their newly created resource:

HTTP/1.1 201 Created Date: Sat, 02 Apr 2016 12:22:40 GMT Location: http://stackoverflow.com/a/36373586/12597 Content-Type: text/html Your answer has been saved! Click <A href="/a/36373586/12597">here</A> to view it. 

If the page will only be used by a robot, then it makes sense to have the response be computer readable:

HTTP/1.1 201 Created Date: Sat, 02 Apr 2016 12:22:40 GMT Location: http://stackoverflow.com/a/36373586/12597 Content-Type: application/xml <createdResources> <questionID>1860645</questionID> <answerID>36373586</answerID> <primary>/a/36373586/12597</primary> <additional> <resource>http://stackoverflow.com/questions/1860645/create-request-with-post-which-response-codes-200-or-201-and-content/36373586#36373586</resource> <resource>http://stackoverflow.com/a/1962757/12597</resource> </additional> </createdResource> 

Or, if you prefer:

HTTP/1.1 201 Created Date: Sat, 02 Apr 2016 12:22:40 GMT Location: http://stackoverflow.com/a/36373586/12597 Content-Type: application/json { "questionID": 1860645, "answerID": 36373586, "primary": "/a/36373586/12597", "additional": [ "http://stackoverflow.com/questions/1860645/create-request-with-post-which-response-codes-200-or-201-and-content/36373586#36373586", "http://stackoverflow.com/a/36373586/12597" ] } 

The response is entirely up to you; it’s arbitrarily what you’d like.

Cache friendly

Finally there’s the optimization that I can pre-cache the created resource (because I already have the content; I just uploaded it). The server can return a date or ETag which I can store with the content I just uploaded:

See Section 7.2 for a discussion of the meaning and purpose of validator header fields, such as ETag and Last-Modified, in a 201 response.

HTTP/1.1 201 Created Date: Sat, 02 Apr 2016 12:22:40 GMT Location: http://stackoverflow.com/a/23704283/12597 Content-Type: text/html ETag: JF2CA53BOMQGU5LTOQQGC3RAMV4GC3LQNRSS4 Last-Modified: Sat, 02 Apr 2016 12:22:39 GMT Your answer has been saved! Click <A href="/a/36373586/12597">here</A> to view it. 

And ETag s are purely arbitrary values. Having them be different when a resource changes (and caches need to be updated) is all that matters. The ETag is usually a hash (e.g. SHA2-256). But it can be a database rowversion, or an incrementing revision number. Anything that will change when the thing changes.