HTTP POST example

Our HTTP method is POST, and https://api.github.com/gists is our resource. We have a header value in the request as well. User-Agent is the header key, with a value of Awesome-Octocat-App. This is what the documentation has specified.

You can take note of the request body in the following screenshot:

This is our request for a POST method.

Our response from this request is depicted here. The server has responded with 201, which means that our request was valid, and the server has carried out the operation successfully:

The server also sends back a resource to us. A new resource has been born and we can fetch data from this.

POST is not idempotent. Idempotent in the REST world implies that as a client when I call an endpoint more than once, I expect to receive the same behavior or I expect to get back the same data. Consider the example where you have to create a contact with a unique email address. The first time you call POST with this email address and other contact details, the server will respond with 201, which means that contact has been created and a unique resource has been published, where you can fetch that data.

If you call a POST method with the same email address, what will happen? The server should return a conflict, 409. The email exists in the data store. So POST is not idempotent: