APIs for data access and management are typically concerned with four actions (the so-called CRUD operations):
- Create - the ability to create a resource
- Read - the ability to retrieve a resource
- Update - the ability to modify a resource
- Delete - the ability to remove a resource
RESTful APIs based on HTTP typically implement these actions using the standard HTTP methods:
- POST - to create a resource
- GET - to retrieve a resource
- PUT - to update a resource by replacing it
- PATCH - to update part of a resource
- DELETE - to remove a resource
Many folks point out that there's not an exact mapping between CRUD operations and HTTP methods, but this list represents best practice and follows the HTTP specification.
For background, the HTTP 1.1 specification defines "safe" and "idempotent" methods . Safe methods don't modify data on the server no matter how many times you call them. Idempotent methods can modify data on the server the first time you call them, but repeating the same call over and over again won't make any difference. Here's a partial list:
The safe and/or idempotent nature of these HTTP methods provides some further insight into how they ought to be used. Notice that POST is neither safe, nor idempotent. A successful POST should create new data on the server, and repeating the same call should create even more copies on the server. GET, on the other hand, is safe and idempotent, so no matter how many times you call it, the data on the server shouldn't be affected.
GET - use it to fetch resources, but don't "tunnel" request parameters through to the server as a way to alter the state of data on the server - as a "safe" method, calling GET shouldn't have side effects.
PUT - use it to update an existing resource by replacing it with a new representation. The data you PUT to the server should be a complete replacement for the specified resource. Although PUT can in theory be used to insert new resources, in practice it's not advisable. Note that after the first PUT request, repeatedly calling the same PUT method with the same data won't change the data on the server more than it already has been (a condition of idempotent methods).
PATCH - use it to update an existing resource by changing some of it's properties. Unfortunately, the PATCH method isn't supported everywhere, but if you want to provide partial updates, it's the right method to use . Newer version of frameworks like Ruby on Rails support the PATCH method; if your server doesn't provide it you'll need to consider some alternatives that I'll cover in the next post.
POST - use it to create new resources. The server should create a unique identifier for each newly created resource. Return a 201 Created response if the request was successful. Best practice appears to be to return the unique ID in the response. POST is also frequently used to trigger actions on the server which technically aren't part of RESTful API, but provide useful functionality for web applications.
DELETE - use it to delete resources; it's pretty self-explanatory.