If you are judging me just by reading the title of this article, then you have every right to think that I am a psycho or that I have never read REST API contracts, but if you going to read the full article, then I believe I can change your perception of me as well as the use of the HTTP POST method.

What Do We Know About HTTP POST Method?

Whenever we see the explanation of the REST API POST method on different sites or in books, we find two major points about when to use POST methods.

1. POST Method is not idempotent.

2. We should use POST to create the resources.

But is this the right explanation of using POST methods, or have we misunderstood the contract of the POST method and now it has been so ingrained in our brains that it has started looking right?

Let's dive deeper into this topic.

When Can We Use POST Method to Update Resources?

As the name suggests, the POST method is used to post information to the server. We do not have any control on how the server will process and save that record (PUT method also sends information to the server, but in addition to that, PUT method asks the server to put (save) that information in a particular place).

We say that POST method requests are not idempotent and have to be used only for creating resources because we do not have control on how the server is going to process that information or where it will save the information. The point here is that not having control on the server side does not mean that the POST method request has to be non-idempotent. Actually, it may or may not be idempotent.

So, we can rewrite the contract for the POST method as:

Use the POST method when:

• you do not have a unique identifier of the resource that you are going to send

• you are trying to send a bunch of resources in one API call, where the state of few/all resources is already persisted on the server.

Still not clear with the concept? Let's look at an example.

Example of Using the POST Method to Create or Update Records

There are many scenarios where we do not know whether we need to create or update the resource. In other words, it may be possible that we do not have an ID (unique location) of where we need to create/update a record.

Let's take an example of marking the attendance of students in a session. We need a GET API /sessions/{session_id}/students, which can give the list of students for that session, and a POST/PUT API, which we want to save attendance.

Consider that the GET API response is below:

students: [
  {
    studentId:student_id_1,
    attendance: present
  },
  {
    studentId:student_id_2,
    attendance: absent
  },
  {
    studentId:student_id_3,
    attendance: null
  }
]

In the above response, we can see that for the first two records attendance has been marked already, and for the third record, attendance is not already marked.

Now to mark attendance, we have two ways. 

1. Send Student Attendance Information in Bulk

If we want to send the list of student attendance details in one API call, then we have to use POST API /sessions/{session_id}/students because few records are for creating a new entry and few are to update the existing entry, and there is no unique identifier that can represent all records present in the request. So for such bulk API calls, the POST method is the only option.

2. Send Each Student's Attendance Information Using a Separate API Call

You can say that we should send each student record using a separate API call (which would cause unnecessary network calls, but let's ignore that for now). POST /sessions/{session_id}/students/{student_id}for creating attendance and PUT /sessions/{session_id}/students/{student_id}/attendances/{attendance_id} for updating attendance. But have you observed the GET API response object (mentioned above)? We do not have any  attendance_id -related information in that, so we don't have any way to identify the resource uniquely. 

You can argue that attendance_id should be present in the GET API, but there would be many cases where would not have control of the GET API contract. Your job would be to parse the data that you are already getting and use that to send information to the server. 

Thank you for reading. Please share your thoughts in the comments.