What is REST? - Representational State Transfer
The internet is full of code and opinions on REST and building RESTful APIs. REST stands for Representational State Transfer but what exactly does that mean and what does it mean for an API to be "RESTful"? Let's first clear up some misconceptions and look at what REST is not. Contrary to popular belief, simply using HTTP methods like GET and POST doesn't make your API RESTful. That just means that you're using HTTP. And just because an API returns JSON, doesn't make it RESTful either. There are plenty of non-REST APIs that return JSON.
Finally, just because your API supports CRUD operations, like creating and deleting, doesn't make it RESTful. RESTful APIs do use HTTP methods and can return JSON and can model CRUD operations but that's not specifically what makes an API RESTful. What REST is all about, modeling your API around resources and allowing clients to perform operations on those resources. In the context of REST, a resource is any object in your API's design domain. Things like documents, users, orders, reservations, and tasks.
In many cases a resource will correlate exactly with a row in a table or an object in the database but that's not always the case. So instead of having API endpoints that are verbs or represent actions you can take in the system, the endpoints in a RESTful API represent resources or collections of those resources. In addition, relationships between data are represented by relationships between the resources in your API.
To sum it up, REST is all about modeling your API around resources, links between those resources, and ways to change or act upon those resources.
REST vs RPC
REST - Representational State Transfer
1) Endpoints are nouns(resources):
api.albertjose.com/users
2) Calling the endpoint is acting on the resource: -
GET api.albertjose.com/users/123
POST api.albertjose.com/users/123
3) Returns resources that were acted upon
4) Resource oriented
RPC - Remote Procedure Call
1) Endpoints are verbs(methods):
api.albertjose.com/getUserInfo
2) Calling the endpoint is calling the method: -
GET api.albertjose.com/getUserInfo
POST api.albertjose.com/updateUser
3) Returns results of the function call
4) Function oriented
REST or RPC?
Remember: Every API is different. One size doesn't fit all
Consider REST when 1) your API is data driven 2) you want to emphasize links between data
Example: PayPal API
Consider RPC when 1) your API is action driven 2) you want to provide a strict set of interactions
Example: Slack API
HATEOAS - Hypertext As The Engine Of Application State
REST APIs and HATEOAS
Responses should include links to the actions available
Single(root) entry point
No need for out-of-band information or documentation
HTTP methods
HTTP methods are the verbs that act on resources in a RESTful API.
1) GET and HEAD
GET is the most common and simplest HTTP verb, it just retrieves the resource that you specify. HEAD is less common, but also simple. A HEAD request behaves exactly the same as the GET request, but it only returns the HTTP headers and doesn't return the resource itself. HEAD is useful when you need to look at headers like Expires to control caching of resources. GET and HEAD are both read-only. A GET or HEAD request should never directly change any application state. For example, a client shouldn't be able to update or delete a resource with a GET request.
2) POST
POST should be used to create resources when the resource ID is not known in advanced. It's also possible to use POST for partial updates to existing resources.
3) PUT
The PUT method can also be used to create or update resources. And this causes a lot of confusion. Should your API use POST or PUT? To answer that question we have to define what it means for a method to be idempotent. An idempotent method is a method that has the same effect when sent once or multiple times. In other words, it doesn't have any side effects.
In a REST API, PUT can be used for creating and updating resources when the ID or URI is known in advance.
4) PATCH
PATCH on the other hand can be used for partial updates because it is not an idempotent method.
5) DELETE
The DELETE method looks simple by comparison. It simply deletes a resource with a known ID. Since it could be retried without any side effects, DELETE is an idempotent method.
Verb : GET
Action : Retrieve a resource
Idempotent? : Yes
Safe? : Yes
Response body? : Yes
Response cacheable? : Yes
Verb : HEAD
Action : Retrieve headers
Idempotent? : Yes
Safe? : Yes
Response body? : No
Response cacheable? : Yes
Verb : POST
Action : Create or partial update
Idempotent? : No
Safe? : No
Response body? : Yes
Response cacheable? : Maybe*
Verb : PUT
Action : Create or full update(upsert)
Idempotent? : Yes
Safe? : No
Response body? : No
Response cacheable? : No
Verb : PATCH
Action : Partial update
Idempotent? : No
Safe? : No
Response body? : No
Response cacheable? : No
Verb : DELETE
Action : Delete a resource
Idempotent? : Yes
Safe? : No
Response body? : No
Response cacheable? : No