REST API

What is API?

API stands for Application Program Interface. There are all kinds of API. API’s are everywhere from computers, smartphones and even refrigerators. Specifically we will be talking about web API’s. It is essentially a contract provided by one piece of software to another piece of software that usually consists of a structured request and response.

One of the best examples of an analogy is restaurant. Think of yourself sitting at a table at a restaurant. You are one piece of software, such as a web application on the client side. The kitchen is the server or the service that processes specific requests. The waiter is similar to the API. It is formatted to take a certain order in a specific way and bring back that certain meal. It is the response you requested. The API is a messenger between running software.

What is REST?

REST stands for Representational State Transfer. It is an architecture type for designing networked applications. It works on relying on a stateless, client-server communication protocol, almost always HTTP(foundation of communication of the web). In order to use REST you need the delivery methods that HTTP offers. REST was created to treat a server objects as resources that can be created, updated or destroyed. An example of a server side object is a blog post in a database. REST can be used by any programming language.

To recap API is the messenger and REST allows us to use HTTP requests to format those messages.

HTTP Methods

Below are some specific methods and requests that can be made to a server through HTTP:

GET — Retrieve data from a specified resource

POST — Submit data to be processed to a specified resource

PUT — Update a specified resource

DELETE — Delete a specified resource

Other requests that are rarely used:

HEAD — Same as GET but does not return a body

OPTIONS — Returns the supported HTTP methods

PATCH — Update partial resources

Endpoints

Below are some endpoint examples. Endpoints are the URI or the URL that our HTTP requests are sent to.

GET api/users

GET api/users/1 | api/users/details/2

POST api/users

PUT api/users/1 | api/users/update/1

DELETE api/users/1 | api/users/delete/1

Authentication

The endpoints like the ones used above without any authentication are called open or public API. Sometimes you need to authenticate before using them. You can do so by registering your application with the providers website and even at times you’ll have to purchase that specific data access. There are a few ways that authentication is implemented.

Usually you’ll use OAuth which involves getting an access token and sending that along with the request. If you attempt to make a request without it you’ll get an unauthorized error. Below is an example of how it works with Github API which is easy to use and great for beginners.

In the example below I’m using curl to make requests. Curl is a tool that is used to transfer data using multiple protocols including HTTP. The example below is sending the token inside of the header.

curl -H “Authorization: token OAUTH-TOKEN” https://api.github.com