Introduction to APIs

In this article

• Introduction
• Web-based APIs
• How the Web Works
• REST — The Good and the Bad
• Conclusion

Introduction

Application Programming Interfaces (APIs) are constructs made available in programming languages to allow developers to create complex functionality with ease. They abstract more complex code away from you, providing some easier syntax to use in its place.

Web-based APIs

Client-side JavaScript, in particular, has many APIs available, providing you with enhanced functionality to use in your JavaScript code. They can be categorized as:

• Browser APIs: Built into web browsers and able to expose data from the browser and surrounding computer environments.
• Third-party APIs: Retrieve data from somewhere else on the web.

Browser APIs

When writing code for the web, there are numerous Browser APIs available, which are typically used with JavaScript. The Browser has APIs available such as Geolocation API or, in my opinion, one of the most commonly used ones, the Fetch API.

They both provide interfaces. For instance, the Geolocation API allows users to provide their location to web applications and the Fetch API provides an interface for fetching resources across the network with a more powerful and flexible subset of features than its predecessors (XMLHttpRequest).

Third-party APIs

Nowadays, very few applications (if any) stand alone. You will most likely need to build internal APIs or consume third party APIs to avoid reinventing the wheel. As applications grow bigger and gain popularity, others will be interested in leveraging your technology or data, which will create an opportunity for you to expand the influence of your application.

With APIs quickly gaining popularity in the world of technology, we've seen a huge growth in its availability over the past twenty years (see Malamud's Analyzing Novell Networks from 1959). Let's quickly highlight two examples of Third-party APIs:

• NASA APIs: Making NASA data, including imagery, eminently accessible to application developers.
• Public APIs: A collective list of free APIs for use in software and web development.

Let's take a quick look at the NASA APIs. One of the most popular websites at NASA is the Astronomy Picture of the Day (in fact, across all federal agencies). NASA claims it's as popular as a Justin Bieber video. The APOD (Astronomy Picture of the Day) API endpoint (will come back to this term later) structures imagery and associated metadata to be repurposed for other applications. Try it here with NASA's demo key (will come back to this term later too). Just make sure to install a JSON formatter for your browser in order to make an easier sense of the data, I'd recommend JSONView.

{
  "date": "2022-04-12",
  "explanation": "{...}",
  "hdurl": "https://apod.nasa.gov/apod/image/2204/N11_HubbleLake_1600.jpg",
  "media_type": "image",
  "service_version": "v1",
  "title": "N11: Star Clouds of the LMC",
  "url": "https://apod.nasa.gov/apod/image/2204/N11_HubbleLake_960.jpg"
}

Can we use Browser and Third-party APIs together?

Yes, we can! Let's take the aforementioned Browser's Fetch API and create a request to get the NASA's Astronomy Picture of the Day. Here's a quick Codepen recreating their APOD website. What's happening behind the scenes? A basic fetch request is really simple to set up.

fetch(path)
  .then((response) => response.json())
  .then((data) => console.log(data));

In the example above, we're using the simplest form of fetch() which takes one argument — the resource you want — and does not directly return the JSON (more on this term later) response body but instead returns a Response object representing the entire HTTP response. So to get the JSON response body content, you need to use the json() method, which returns the result of parsing the response body text as JSON. You can read more information, here, on Using the Fetch API.

How the Web Works

Before we move any forward, let's explore some basic concepts on how the web works. What happens when you view a website from a web browser on your computer or phone.

What exactly happens? (An oversimplified story)

When you type a web address into your browser:

• The browser goes to the DNS (Domain Name System) server, and finds the real address of the server (website's IP address) where the website lives on, then
• The browser sends an HTTP (Hypertext Transfer Protocol) request to the server, asking it to send the website back to the client(browser), then
• If the server successfully accepts the request, it will respond with a "200 OK" message and send back the website to the client, and finally
• The browser displays the website for you.

A small note on DNS

Real web addresses aren't the nice, memorable strings you type into your address bar to find your favorite websites. They are special numbers that look like this: 63.245.215.20. These are called IP addresses, and they represent a unique location on the web. DNS servers translates human-friendly domains (such as mozilla.org) to numeric IP addresses (such as 151.106.5.172).

Technically speaking, websites could be reached directly via their IP addresses. You can try this by replicating a DNS request using a tool like IP Checker.

What is Hypertext Transfer Protocol (HTTP)?

HTTP is a protocol for fetching resources, such as HTML. It was designed for communication between web browsers and web servers following a stateless and simple client-server model.

Let's make a simple HTTP Request

Send an HTTP message: let's try inspecting what's happening behind the scenes with NASA's APOD API. To make this request on the Browser: 1) Open a new Tab, 2) Open the DevTools from your Browser and then view the Network requests, and 3) visit the URL.

/** Request Headers*/
GET /planetary/apod?api_key=DEMO_KEY HTTP/1.1
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
Host: api.nasa.gov

View the response sent by the server

/** Response Headers*/
HTTP/1.1 200 OK
Date: <date>
Content-Type: application/json
 
/** Response Body*/
{...}

We can replicate the request above using an API platform tool like Postman: 1) Go to Postman's web application, 2) use your credentials to create an account or log in and create a Basic HTTP Request and 3) Send a GET request with the APOD API's URL https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY.

Identifying Resources on the Web

The target of an HTTP request is called a "resource" (a document, a photo, anything else). Each resource is identified by a Uniform Resource Identifier (URI) (URLs are the most common form of URIs known as web addresses) used throughout HTTP for identifying resources. Let's take a look at some examples of URLs.

https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY
https://apod.nasa.gov/apod/image/2204/DevilsWay_Kiczenski_960.jpg

Here you can find more information on the anatomy of a URL.

REST — The Good and the Bad

Representational State Transfer (REST) is an architectural style that guides the design and development of processes to interact with resources on the web. An API that complies with most or all of its guiding constraints is considered to be a RESTful API for a more comprehensive guideline refer here.

REST uses all the advantages of the HTTP like request verbs, URI, media-types, caching etc. Since REST services work like normal websites, they are easy to create and consume compared to other styles of web services.

Every RESTful API starts with what Fielding calls the *Null Style**. It all starts with the system needs as a whole, without constraints, and then incrementally identifying and applying constraints to elements of the system in order to allow forces that influence system behavior to flow naturally, in harmony with the system. This style emphasizes restraint and understanding of the system context. So let's quickly catch up on what should we know from its guiding constraints.

Client-Server

• What is it? — Separation of concerns is the driving principle behind this constraint, separating the user interface (client) from the data storage (server).
• The Good — By doing so, we improve portability across multiple platforms and improve scalability by simplifying the server components. This separation allows each component to evolve independently.

Stateless

• What is it? — Client-server communication must be kept stateless in nature, such that each request must contain all the information necessary to understand the request (and cannot rely on any stored context on the server).
• The Good — Visibility is improved because the system doesn't have to look further than the request itself to determine its nature. Reliability is improved because it eases the task of recovering from partial failures. Finally, scalability is improved because it allows the server to quickly free resources for additional requests and simplifies implementation because it doesn't have to manage resource usage across requests.
• The Bad — The disadvantage is that it may decrease network performance by increasing the repetitive data (per-interaction overhead) sent in a series of requests, since that data cannot be left on the server in a shared context. In addition, placing the application state on the client-side reduces the server's control over consistent application behavior, since the application becomes dependent on the correct implementation of semantics across multiple client versions.

Cache

• What is it? — The addition of cache components to form a client-cache-stateless-server architectural style in REST. A cache acts as a mediator between client and server in which the responses to prior requests can, if they are considered cacheable, be reused in response to later requests that are equivalent and likely to result in a response identical to that in the cache if the request were to be forwarded to the server.
• The Good — Potential to partially or completely eliminate interactions, improving efficiency and user-perceived performance.
• The Bad — Cache can decrease reliability if stale data within the cache differs significantly from the data that would have been obtained had the request been sent directly to the server.

Uniform Interface

• What is it? — The application of generality or uniformity between component interfaces.
• The Good — The overall system architecture is simplified and the visibility of interactions is improved. Implementations are decoupled from the services they provide, which encourage independent evolvability.
• The Bad — It degrades efficiency, since information is transferred in a standardized form rather than one which is specific to an application's needs.

Layered System

• What is it? — Architecture composed of hierarchical layers containing component behavior such that each component cannot see beyond the immediate layer with which they are interacting.
• The Good — Layers can be used to encapsulate legacy services and to protect new services from legacy clients. Intermediaries can also be used to improve system scalability by enabling load balancing of services across multiple networks and processors.
• The Bad — They add overhead and latency to the processing of data, reducing user-perceived performance. For a network-based system that supports cache constraints, this can be offset by the benefits of shared caching at intermediaries. Placing shared caches at the boundaries of an organizational domain can result in significant performance benefits.

Conclusion

For a more detailed explanation on design, structuring and maintaining RESTful APIs see here.