Understanding REST API Architecture
Many APIs are built on what is referred to as a RESTful framework. REST stands for representational state transfer, and is a convention for building HTTP services. Before REST, there was SOAP, and soon, many will likely transition to Graph QL. However, REST is still highly-utilized today, and worth familiarizing yourself with.
APIs (application programming interface) allow programs to “talk” to one another, and a RESTful framework is a very popular convention for web API structure. The framework defines how the client requests are structured, as well as what data the server returns back to the client. When following REST convention, various clients hit the same endpoints, perform the same actions, and receive uniform responses.
That means that the endpoints, or URLs to which we can send an HTTP request for data, follow certain conventions. These URLs should allow you to request information, send information, update information and delete information. Long ago, every API was implemented differently, with no real logic behind the structure, but RESTful APIs respond to read, create, update, and delete requests in a standardized way.
REST organizes around resources, and uses the HTTP verb to indicate how we want to interact with those resources. For example, on http://farmanimals.com/cows, “cows” represents the resource that our server is revealing. REST needs a way to access and modify the resource data, and it does so with either the example URL provided previously, or http://farmanimals.com/cows/1 depending on the desired action. In case you’re not familiar with the four basic HTTP actions, here’s a quick reminder:
- GET acts upon the entire resource and will return an entire list of that resource, unless the URL includes an ID, in which case it retrieves a single instance of that resource which matches the correct ID
- POST is used to create a new instance of the resource. It should be used on the entire resource by not using an ID in the URL
- PUT/PATCH works very similarly to POST, but instead of creating a new instance of a resource, it updates one that already exists.
- DELETE will destroy an individual instance of a resource using an ID
The ID-less URL is used for actions on the entire resource, including GET, and POST, while the URL that includes the ID is used for GET (when you just want to access one individual cow), PUT/PATCH, and DELETE.
TL;DR: The URLS used in RESTful APIs represent resources, and they support creating, reading, updating, and deleting from that resource using the HTTP actions GET, POST, PUT (or PATCH), and DELETE, which you specify in your request. API frameworks make using APIs a more uniform process, and therefore, easier for developers who need to access the information.
