Modern REST APIs

Matthew Fisher - November 1, 2021

Cover image for article: Modern REST APIs.
local_offer APIs
An overview of modern REST APIs and how they are used in web applications.

Introduction

In this article, I will discuss the basics of a REST API and how they are used in modern web applications. I will also go over some common design patterns that have been implemented by APIs such as NetworkCalc's.

By the end of this post you should be familiar with what REST is and why it's so important for developers to know about when building applications today. You should also have a better understanding of how these types of APIs work under-the-hood and why they're so powerful for application development teams across all industries today.

What is REST?

In today's world, many businesses use REST APIs to power their web applications. As a system administrator or network administrator, you should know how to use them as well as what features are available in each API.

Let's clarify what REST is first. REST stands for Representational State Transfer. REST is an architecture built on top of HTTP that uses common HTTP verbs like GET, POST, PATCH, PUT, DELETE to perform actions on resources. A resource is a collection of data attributes that describe some concept of interest. REST APIs allow for the operations commonly referred to as CRUD: CREATE, READ, UPDATE, DELETE.

As an example, a subnet resource may have attributes network_address, broadcast_address, and assignable_hosts. REST interfaces use JavaScript Object Notation (JSON). The example below shows the JSON representation of a request to read the subnet resource, which in general terms would be the a response to the request GET /subnet/192.168.1.1/24:

{
 "subnet": {
  "network_address": "192.168.1.1",
  "broadcast_address": "192.168.1.255",
  "assignable_hosts": 254"
 }
}

For more technical details on the guiding principles of REST APIs, how they are structured, and their properties, read the What is REST article on REST API Tutorial.

Making REST Calls

When working with REST APIs, there is a client-server architecture. The client is your web application, a browser, or a bash or PowerShell console. The server is the remote site that serves up the resource. When a client requests a resource from the server, that an API call is made to the server. There are many ways to make REST calls. Since REST API services are accessible over HTTP(S), any networked client that can reach the API service's host service or endpoint can interact and make API calls.

Most API services implement a version of CRUD REST methods described above. In order to use most modern API services' CRUD API calls you have to include the API's host URL with GET, POST, PATCH, or DELETE requests that reference the endpoint or resource URI. For example, a simple GET request that looks up DNS records for example.com using NetworkCalc's DNS Tools API might look like this:

dns_service = HTTPClient('https://networkcalc.com/api/dns/')
response = dns_service.get("example.com")

This architecture is a call-and-response style architecture, where the client makes a request to CREATE, READ, UPDATE, or DELETE a resource and the server response with the result. To expand on the CRUD operations as implemented with HTTP(S), they are commonly used in the following way:

Many methods exist for interacting with REST APIs. API calls can be made programmatically using a programming language such as JavaScript, Java, or C++. API calls can also be made using command line tools that are built into API frameworks or via API-specific command line tools. Some API developers publish Software Development Kits (SDKs) that can be used to interact with APIs without making explicit calls. API calls can even be made using web browsers, such as when an API is exposed in the form of a website.

Authentication and Authorization

Many API calls require authentication and authorization to access server resources. API keys are sometimes used for this purpose, especially when the API key is passed as an HTTP header. API keys can also be used to enforce API calling quotas or rate limits, which set limits on how many API calls a developer or application can make on a monthly, daily, or minute-by-minute basis.

Authorization schemes such as OAuth are often preferred over API keys because they are generally more secure. Instead of passing API keys around in HTTP(S) headers, there is two-way handshake that occurs with OAuth, where the client passes a set of credentials (a client ID and client secret), the server checks the client's authorization for accessing its resources, the server provides the client with an ephemeral token such as a bearer token, and the client can use the bearer token in subsequent API calls for a limited amount of time.

The OAuth authorization scheme for NetworkCalc is illustrated below:

Diagram of NetworkCalc API authorization scheme

API Documentation

It is important to document the data types supported by an API, especially if there are any restrictions about what type of data can be passed through API calls. Making this documentation searchable helps developers find the information they need quickly and efficiently. The API should also describe how error messages will be returned and at what HTTP status codes mean (200 = OK, 400 = Bad Request). This ensures that errors can be anticipated and handled properly throughout the application without requiring extra logic to check return values and make further API calls.

NetworkCalc API documentation attempts to do exactly this: provide developers with detailed documentation, response formats, error code descriptions, and examples. When developers have a solid understanding of how API requests and responses work, they can spend less time debugging and spend more time integrating the API into their applications.

Summary

API documentation is often treated as an afterthought in API development. API companies are under pressure to develop new features and functions quickly, leading to API teams trying their best to stick close to API functionality while handling API documentation on the side.

If you develop APIs, don't make this mistake! API developers that provide comprehensive API documentation will have happier customers since end users can more easily integrate with APIs. This results in faster iteration of API integrations, which helps business prioritize what services should be part of an API suite.

If you use APIs in your own development, look for APIs that have good documentation that is updated frequently. API documentation that is out-of-date means that API providers are not iterating on their API features, which will make it harder for you to integrate with the API – and will also delay any feedback from customers who want to use your API integration.

In this article, I explored some of the details of what makes up modern REST APIs. I discussed REST as an architectural style that sits on top of HTTP(S) and uses common HTTP verbs - GET, POST, PATCH, DELETE - to implement the CRUD operations - CREATE, READ, UPDATE, DELETE.


Subscribe for more articles like this.