What’s a REST API?
REST stands for Representational State Transfer. It is really just another layer of meaning on top of HTTP.
API stands for Application Programming Interface, it is a programmatic interface that makes it easier for things outside of our application to interact with our application, where all communication is done through HTTP, and the burden of creating the interface is on the users of the API, not the creator.
Example:
A server running for handling the scores of our game from all across the globe and want to be able to update scores whether our players are using a PC, a mobile device, or a tablet.
Resource
In a REST API we have these things called resources. Usually a resource is a model in your application.
Maybe, again, you’re holding on to player scores for your game. So a player would be a resource, and so would a score.
Typically your resource name should be plural, because the action is to get a collection and you wouldn’t call a collection of players player.
Endpoint (Nouns)
Resources are things we want to retrieve, create, modify, or delete through our API at specific URIs which are called endpoints. Endpoints represent either a single record or a collection of records.
Methods (Verbs)
If endpoints are nouns then methods are verbs. Unlike endpoints, actions take on resources not in the URL, but they’re represented by the type of request the client makes to the API.
Main verbs / HTTP methods:
- GET is used for fetching either a collection of resources or a single resource.
- POST is used to add a new resource to a collection (e.g. POST to /players to create a new player)
- PUT is used when we want to update a record – we wouldn’t use PUT on a collection.
- DELETE is for deleting records.
Version
api/v1/users/567
We want to always provide a version number for our APIs, and we want to make sure that legacy APIs exist for as long as possible.
HTTP Headers
Request Headers
Accept Specifies the file format the requester wants.
Accept-Language Specifies the human language.
Cache-Control Specifies whether the response can be generated from a cache or not.
there are many more useful headers…
Response Headers
Content-Type This should match the requested type (e.g. text/javascript)
Last-Modified Inform the requester when the data was last modified
Expires How long the data is considered good
Status Status codes tell about the state of the requester’s request (e.g. 200, 404, etc.)
200-299 All is good and everything is OK. (e.g. 202 let’s the user know that a record has been created)
300-399 Request has been understood, but requested resources are now located somewhere else.
400-499 Errors and bad requests.
500-599 Server-end errors.