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.