HTTP 200, 201 & 202
When a Cloudant operation succeeds, it will reply with an HTTP code that is between 200 and 300. Sometimes a client application might see a 200 response and in other circumstances a 201 or 202 response. This blog post explains the difference between these response codes.
Photo by Kenny Eliason on Unsplash
The HTTP 200 response is the classic HTTP response that means “OK”. It can can be found for most operations that fetch documents singly or in bulk:
- Fetching a document by id
- Listing documents in a database
- Querying MapReduce views
- Querying using a selector
- Querying a search index
- and many others.
HTTP 200 means that the API call was well formed and the response will contain the document or documents requested.
Writes in cluster🔗
Cloudant clusters are multi-node distributed systems, with three copies of each document and each index being stored on separate machines. The database is eventually consistent so the service prefers to be available rather than consistent i.e. if a node is down, it will continue to service reads and writes, even if it means that the failed node will have to catch up when it comes back online.
When a document is written to a Cloudant database, whether it be an insert, update or delete operation, the node handling the request calculates which three nodes need to store the document. The three nodes are sent the new request and the handling node responds to the user as soon as either:
- (At least) 2 or the 3 nodes respond that they have accepted the request. This results in an HTTP “201 Created” response.
- One node accepts the request and other two do not (yet). This results in an “HTTP 202 Accepted” response.
Should I worry about an HTTP 202 response?🔗
In short “no”. A HTTP 202 response means that the data is safely stored in at least one Cloudant node and the others have already received the update, or will in due course via Cloudant’s internal replication. It may be that the other nodes already have the document revision in question, but they were too slow to respond to the coordinating node. In any case, no further action is required.
The Client Libraries all treat any 2xx response as a success and client applications should follow this example.
For more details on how Cloudant’s clustering works, see this blog post.