Home » Study Notes » Web API Study Notes

What is an API?

API is an acronym for Application Programming Interface. They are tools provided by a third party to allow developers to interact with the data and functionality stored on their service.

A popular use for API’s is authentication, you’ve seen this when having to sign up to a website for the first time. Most of websites these days allow you to sign in via Facebook or Google, the authentication process is handled via their own API.

The Backbone of APIs

To understand APIs we need to understand HTTP request methods. They are the building blocks of the web and from which APIs are structured from. Some may know them as “HTTP Verbs”, we’ll only be looking at a few of these since they’re the ones we’ll mainly be interacting with to carry out our CRUD operations.

CRUD stands for Create, Read/Retrieve, Update and Delete, they are the main operations we’ll be using to interact with an API.

Please note that APIs are not necessarily tied to using HTTP, however it is common to see them using it as their transfer protocol.

HTTP Request Methods

GET

Only used for retrieving data, the GET method requests a specific resource using a Universal Resource Locator OR Universal Resource Identifier (URL/URI). We see this in action everyday when trying to access different websites. We enter the URL of a website into our browser. The browser sends a GET request along with the given URL to a server. Once the server has received the GET request, it sends back a RESPONSE. The BODY of the response is what contains the HTML files your browser will read to display an output. (READ/RETRIEVE operation).

Head

Similar to the GET verb, however HEAD only requests the headers of a given URL. Normally this is used if you wanted to see details of the body. If you’re expecting a URL to download a file, you can use the HEAD verb to retrieve the file size.

Post

POST requests are usually sent via HTML forms. They cover functions like adding a new user through a sign up model. (CREATE operation).

Put

Uses a given URI to create a new resource or overwrite a specific resource with the requested data. (UPDATE operation).

Patch

PATCH requests are similar to PUT, they provide a set of instructions on how to update a specified resource instead of replacing it.

Delete

Deletes a specified resource given in a URL. (DELETE operation).

The Importance of Headers

Headers store important information about requests and responses, they’re stored in specific key and value pairs. They consists of a name, for example “Content-Length” followed by a colon “:” then by it’s value. Typically they contain information such as an API key, other authentication data and/or the type of content you’re receiving or posting. An example of a key value pair would be the status code. Status codes provide us with a number which tells us about the activity on the server. A popular status code would be “error:404” (Page not found).

Responses

Typically, the body of the response is what you’re expecting to receive when you write your GET requests. Its stored in JSON (JavaScript Object Notation). This is because JSON provides a great way to structure requested data, take a look at the below example.

I created a request to an IP Tracking API, as a result of the request, I received the below response. You can clearly see the data separated in key value pairs.

ip_address_lookup: Array [ {…} ]

0: Object { status: "ok", ip: "82.4.251.122", asn: "5089", … }

asn: "5089"

city: "London"

country: "GB"

ip: "82.4.251.122"

isp: "Virgin Media Limited"

latitude: "51.50853"

longitude: "-0.12574"

postalcode: "WC2N"

region: "England"

status: "ok"

time: "+01:00"

The RESTful Approach

The acronym stands for Representational State Trasnfer, the name was coined by Roy Fielding in 2000. REST is a proposed architecture that outlines a set of constraints in order to standardize the development and use of APIs. The architectural constraints are:

Uniform Interface

As the name implies, APIs must have a consistent interface to identify, interact with or manipulate resources. Usually this is done by using a URI standard for resource identification and HTTP verbs for interaction. The goal is to make all APIs have a familiar feeling, if you’ve used one, you could use a similar approach on another.

Client-Server

This constraint advises that client apps and server apps need to operate independently from eachother. Clients only need to know the URI of a required resource.

Stateless

Because they rely on HTTP for resource transfer RESTful APIs are, by nature, stateless. Meaning that the data is stored within the resource and each request is it’s own operation, this allows for highly scalable web services since there is no need to retain data between the client and server. Note: Other factors, such as the hardware on the service’s back end may limit scalability

Cacheable

Caching can help with performance on the client end. It’s actually standard practice within the web, webpages are cached within your browser as soon as you access them. Caching also reduces the load on the server which can help scalability.

A well set up caching helps the developer interact with resources effieciently, which results to fewer client-server interactions.

Layered System

Within this constraint, you are allowed to use a layered architecture. You can deploy the API on one server, store the data on a second and authenticate requests on a third server.

Code on demand (Optional)

Most of the time when we’re requesting resources, we’re expecting a JSON or XML representation of the resource. Some APIs may actually return executable code to help with part of your app, for example you may provide addtional code to load a UI widget onto a requestors app.

Study Diary

Web API Study Notes