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 are REST APIs?
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.
APIs provide developers with a way to extend an application with new features and functionality to make it more useful. APIs act like glue by holding different applications and data together using a common set of protocols. Network APIs make it possible to connect and communicate over computer networks like the Internet. They are common in modern life, especially with so many online interactions happening through mobile devices or desktop computers, which have capabilities that were unimaginable in the early days of computing.
Let's clarify what a REST API is. 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 responds with the result. To expand on the CRUD operations as implemented with HTTP(S), they are commonly used in the following way:
POST- CREATEs a new resource on the server.GET- READs a resource from the server.PATCH- UPDATEs a resource on the server.DELETE- DELETEs a resource from the server.
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 authenticating a user, 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 NetworkCalc uses for its network APIs is illustrated below:
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 provides developers with detailed documentation, response formats, error code descriptions, and examples for its network APIs. 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. Documentation helps with this.
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.