POST vs PUT vs PATCH

[scottetass]

Hi all,

I wanted to provide some information with regards to POST/PUT/PATCH and how they work in the API.

POST is for creating new records. You must provide all the fields in the request with values. Whatever values you provide will be saved to the database.

PUT is for updating existing records. Again, you must provide all the fields in the request with values. Whatever values you provide will be saved to the database.

PATCH is for updating specific fields for an existing record. PATCH uses a special JSON syntax for providing fields with values and the operation to perform on the field.

Take the employee endpoint as an example:

URL: 
https://<your domain>/api/<company>/employee/1000011/information

Request body:
[
    {
      "op": "replace",
      "path": "/birth_date",
      "value": "1989-02-12"
    },
    {
      "op": "replace",
      "path": "/indig_status",
      "value": "4"
    }
]

This would 'replace' the birth_date and indig_status fields with the values provided and leave everything else as is in the database.

More information regarding the PATCH syntax can be found here.

Why can't I use PUT for updating only specific fields?

If using PUT you would be forced to provide all fields for the endpoint. If you provide values for the fields you want updated but provided blank or null values for fields you didn't want updated, we can't tell what your intention is with those fields - did you want them blanked out on the database or did you only provide them with blank values because you had to?

This is where PATCH comes in, you only need to provide the fields you want to act upon and nothing else. Whatever fields you leave out of the PATCH will preserve their values in the database.