There’s A Method To My Method: RESTful API Methods
As I mentioned in last week’s post, I’ve been spending a lot of time working with APIs lately, integrating them into a variety of different applications — which has given me a good reason to go back to the basics and reinforce the fundamentals of RESTful design.
Today, I want to talk about RESTful API methods/verbs.
There are four basic operations you might need to use when working with data, often referred to as the CRUD convention: Create, Read, Update and Delete. When developing or integrating a REST API, you want to have easy access to CRUD operators so that you can retrieve, add, edit or delete the data that you require.
Luckily, there are HTTP methods — also referred to as verbs — that can be incorporated when making an API call, all of which match our CRUD operators.
CRUD Actions | REST Methods
Create | POST
Read | GET
Update | PUT / PATCH
Delete | DELETELet’s take a peek under the hood and see what each of our REST methods do for us.
GET
Probably the most widely used of the REST methods, GET allows us to retrieve read-only information from a resource — meaning that data will not be altered or changed in any way. This makes it one of the safest HTTP requests we can make. If all you want is to read the data from an API, this is your best option.
Generally, you want GET responses to be idempotent, meaning that if you make the same request, you’ll get the same response every time — at least until the data is modified in some way by another method.
Common Responses:
- 200 — Your response was successful! A resource was found and the API should return information from that resource in the response you receive.
- 404 — An error indicating that there is no available resource that matches the requested data.
- 400 — If the client enters information that is not formatted correctly, then this error will occur. For example, if an address requires a Zip Code, but no Zip Code is entered.
POST
A POST method is going to create a brand new instance of a resource and push it into a collection of already existing resources. A User signup page is a perfect example of where one might utilize a POST method, perhaps on submit, after a User has entered all of their credentials.
If you use a POST method, it should be noted that they are not idempotent — like our GET method. Rather, if you POST two identical instances of an object, two separate objects will be created. Even if all the attributes are identical, they are different objects.
Common Responses:
- 201 — Identifies that a new object has been successfully created.
PUT
We’ve determined the best method to use to add a new instance of a resource, but what if you want to edit or change one that already exists? A PUT request is perfect for this type of problem. PUT requests are designed to change a single resource in its entirety.
Common Responses:
- 200 — Indicates that there has been a successful change and that your request has been processed.
DELETE
If you no longer require a specific resource, the DELETE method allows you to remove it from the API. It’s as simple as that!
Common Responses:
- 200 — The resource was successfully deleted.
- 404 — An error will be returned if you’ve already deleted a resource, because if it no longer exists, it can’t be found to be deleted.
PATCH
There is a fifth HTTP method that you may occasionally see brought up and that is PATCH. PATCH makes a partial modification to a resource.
How is this any different than PUT?
PUT replaces the entirety of the resource. PATCH only replaces certain elements of that resource. For that reason, PATCH is often the best option if you only intend on changing specific attributes and not the resource as a whole.
It should be noted that not every browser supports PATCH requests, so they should be used in a limited capacity.
With these five REST methods, you can operate on the data contained within an API, using it to enhance your web applications.
