An introduction to APIs

API

API stands for Application Programming Interface which is an application programming interface for the Web.

An API can be considered as a backend web application.

Types of API

SOAP (XML based)
REST API (JSON)

We will be concentrating on REST API’s as it is currently the industry standard

Why do we use API’s?

client-server communication
- mobile app and backend web server
- frontend web app and backend web server
- desktop app and backend web server
communication between different systems (ex: google and microsoft)
syncing data from multiple platforms (ex: websites and mobile apps)

REST API

REST is acronym for Representational State Transfer and allow secure exchange of information via standardised resources over the internet.

How do REST API’s work?

Client and servers exchange resources via standardised
- protocol (http)
- data format (JSON)
Resources can be:
- Data (ex: formatted database search results)
Clients:
- Carry out operations towards resources
- For example:
  - Client requests information from resource
  - Client updates resource
Operations can be conducted on resources
- Some common operations are:
  - GET - request information from resource
  - POST - send information to server to create/update a resource
  - PUT - Similar to Post
  - PATCH - Modify some parts of a resource
  - DELETE - Delete specified resource

Key principles of REST API’s

There are many principles behind the architectural style of REST API’s. The most important ones are as follows:

Uniform Interface

Enforces standard format for resources and operations
Statelessness

Allows concurrent/simultaneous requests to be processed without affecting other requests.

Benefits of REST API’s

Scalability

System can be easily scaled with time. Performance can be enhanced with caching and load-balancing.
Flexibility

Allows system to be easily modified without rewriting application code on every platform. Additional functionality can be added without affecting other parts of the system.
Independence

Client and server apps are independent and can be written in any programming language.

Underlying technologies can be changed without affecting the frontend or backend as well as the communication

Communication between client and server

Simple client-server

Untitled

Client Request

The client communicates with the API via API Endpoints also know as URI (Uniform Resource Indentifier).
The client makes an http request to the URI containing http headers and parameters(operation)

When a client communicates with an API, it has to specify:

what (protocol {http} and application format {json})
where (API endpoint/URI) - routes
action (operation)

API Endpoints(URI)

An endpoint is simply a URL. An example is shown below:

https://mysite.com/users

Http Request

The client makes an http request to the server on the specified URI endpoint.

Http headers which may contain:

Query parameters (GET requests)
Data (POST requests contain the payload)
Application Type (JSON)
Authorisation token (Security purposes, oauth, bearer tokens, api keys,etc)
Cookie parameters (Authentication purposes)

Operation

The operation informs the server what to perform on resources before sending back the result in JSON format to the client.

Operations may be:

GET - request information from resource
POST - send information to server to create/update a resource
PUT - Similar to Post
PATCH - Modify some parts of a resource
DELETE - Delete specified resource

Client Request Overview

Untitled

Sample HTTP Request

A sample http request is shown below:

POST https://adventure-works.com/orders HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 57

{"Id":1,"Name":"Gizmo","Category":"Widgets","Price":1.99}

Server Response

The server:

performs the operation the resource
formats the result in JSON format
adds a http status code and JSON data to the http response
sends back the http response to the client

Common HTTP Status codes

200: Generic success response
201: POST method success response
400: Incorrect request that the server cannot process
404: Resource not found

Sample HTTP Response

The following example shows the payload (JSON) returned by the server after a get request was performed:

Get Request

Untitled

API Response

The response status code is 200 (success) and the payload is shown below. The JSON response contains the parking information from the parking resource.

{
    "location": {
        "lng": 57.50108208351377,
        "lat": -20.16167507202768
    },
    "ID": "01662563976508",
    "address": "test Parking",
    "description": "Secure parking with guardian in building",
    "parkingSlots": 1,
    "parkingType": 1,
    "hourlyRate": 100,
    "sellerId": "01662563291170",
    "createdOn": "2022-09-07T15:17:40.606Z"
}