APIs 101 – everything from client-server to REST
Tags: architecture, computerscience
Published: 2020-05-04 01:05:10

For the original blog, visit: https://nihalpotdar.home.blog

What is a HTTP request?

When you click on any website, the browser sends what is known as HTTP request to a server which can be located by the specified address. This address is known as an URL (Uniform Resource Locator) and is where the browser request is directed. The data sent back, is known as the response.

Anatomy of an URL

The URL where the browser makes a request is known as the  endpoint. The root endpoint is the base URL, it is the scheme+domain name. The path refers to the requested resource, it is the specific piece of information you are trying to access. 

Types of HTTP requests

There are different types of HTTP requests that we can make, also known as HTTP request methods. These HTTP methods are used in different ways corresponding to the task which is sought to be completed. While there are 9 HTTP request methods, the most popular ones are the GET, POST, PATCH, and DELETE methods. A good analogy to think about these methods is to think about how you would use them with a database? For an example: to create a row, you would most likely use the POST method, to access existing information, you would most likely use the GET method, while to delete a row, you would most likely use the DELETE method.

When we access a website from the browser, the browser makes a GET request to the server associated with the URL that we enter. GET requests are normally made to access information. All the information in get requests is contained in the URL, in what is known as query parameters. Query Parameters are always preceded by a “?”, are in a variable and response format, and are separated by a “&”. 

As the database analogy, POST, PUT and DELETE requests are normally used as per what their name indicates. These requests can have a body which is a piece of attached information which is sent to the server. The body is not a part of the URL and hence, more important information is generally placed in the body. In a GET request, the information is encoded in the URL while in other POST, PUT and DELETE requests, the information can also exist in the body. While we can only make GET requests from the browser, we can make these other types of requests using external tools such as Postman which will be later discussed in this blog.

When we send a request, we can also add headers. Headers provides information about the request to the server and contains information regarding authentication, here’s a list of all headers.

Examples of headers

{

“Content-Type” : “application/json”,

“Username”: “***”,

“Password”: “***”

}

As you can see, an username and password is not the safest way to authenticate yourself with an API. A better approach can be the use of the OAuth standard which does not involve directly sharing your credentials and instead, a limited-time access token.

API’s

What is an API (Application Programming Interface)? 

An API is just a set of rules that defines the interaction between two programs of some sort. For an example: the Google Maps API defines the interaction between your website and Google’s server which contains the maps data.

Often, the aim of API’s is to make some kind of a task easier for developers to perform. For an example, the aim of the GitHub API is to allow developers to get data about GitHub profiles and repositories without the developers having to write code which will get this information for them. A key benefit for companies which do build public APIs is that it allows them to track how different sets of users are interacting with the data on their platform, by requiring authentication. This is also a great way for companies to popularize their platform by allowing individual developers to use the data to the effect of building better applications.

Additionally, companies can also have internal APIs which are only meant for internal user. For an example, an internal API of stock prices in a finance company.

Try out the GitHub API. 

API Specifications

While there are a variety of APIs, there are certain criteria which an API can enforce in order to ensure security, conformity, and to maintain a standard. These criteria are known as specifications, and these specifications all-together are known as standards. The most popular standards are SOAP (Simple Object Access Protocol) and REST (Representational State Transfer). REST currently powers about 70% of all web APIs. However, prior to the REST standard which was introduced in the year 2000, SOAP was the most popular API standard which used XML.

A simple way to visualize REST APIs is to think of a server which returns information rather than the content for a website. Other RESTful Constraints include Client Server Architecture, Stateless (does not care about the state of the client), cacheability (should data be cached or not), layered system, uniform interface, code on demand (optional). A more in-depth analysis will be included in a later blog.

Data is normally exchanged to and from an API using the JSON format, JSON stands for JavaScript Object Notation. JSON is intended to be written in key-value pairs and does not require the use of a programming language as it is meant to read as text.

JSON Example

{

“name”: “Test”,

“age”: 10

}

What’s a schema?

An API schema is a guideline which establishes how an API is built and how users can interact with an existing API by listing all the endpoints and their associated HTTP action. A schema is primarily designed for external use, in either YAML or Swagger. In the schema, an API can also specify what format for the request and response such as JSON. It is generally considered as good practice for developers to document their APIs by building a schema.

Get Started with Postman and list your repositories

Additional Information:

Difference between HTTP and HTTPS

HTTP stands for HyperText Transfer Protocol while HTTPS stands for HyperText Transfer Protocol Secured. HTTP is susceptible as there is no encryption as the data is transferred from the browser to the server. HTTPS data is encrypted.

OAuth

OAuth is a centralized means of authentication which prevents users from having to provide their information directly to third party applications. Instead they get routed to a trusted website from where they can log in (Google, Twitter…). Organizations also realized that they could also use this within a single domain as to centralize where users are log-in (all google services login pages are directed to the same url for login) which is more secure and easier to manage

URI vs URL vs URN

An URI is an Uniform Resource Identifier, accessing a resource on the internet by either using its name or its location or both (name: bob smith, location: 111 harper street, reindeer city, NJ). An URL – Uniform Resource Locator, accessing a resource on the internet with its location (location: 111 harper street, reindeer city, NJ) – consists of two parts: the protocol and the domain. An URN – Uniform Resource Name, accessing a resource on the internet with its name (location: 111 harper street, reindeer city, NJ)

Additional Links

I cannot vouch for the authenticity of these links nor do I claim ownership for them, but only that I found them useful when I was learning about these topics.

Using a REST API - https://www.smashingmagazine.com/2018/01/understanding-using-rest-api/

Build your own API - https://www.youtube.com/watch?v=0oXYLzuucwE

Mock Testing Server - https://requestbin.com/

Webhooks - https://zapier.com/blog/what-are-webhooks/