Developer Handbook
The Basics of RESTful APIs: A Beginner's Guide to Modern Web Communication

The Basics of RESTful APIs: A Beginner's Guide to Modern Web Communication

Ademola Thompson's photo
Ademola Thompson
·

6 min read

Table of contents

APIs (Application Programming Interfaces) are like bridges that allow different software applications to communicate. Think of APIs as middlemen who carry requests and responses from one system to another.

APIs make it possible for backend systems to communicate with frontend applications. For example, when you use a social media app, the app (or more specifically, the frontend) fetches information from the backend API to show you what you see on the screen (posts, comments, etc). APIs are very important to modern software, as they power almost everything from websites to mobile and enterprise applications.

Although there are different types of APIs, RESTful (or REST) APIs are the most popular and widely used. In this article, you will learn about REST APIs and why they are useful.

Understanding REST APIs

A REST API is an API that follows the principles of the REST architectural pattern for designing networked applications.

REST is the short form for REpresentational State Transfer. It is a set of guidelines or principles that determines how to build an API. Although REST has its own policies, it is not a standard or rigid protocol because every developer can implement REST in their way.

REST APIs usually revolve around the concept of resoures. Resources can be in different formats such as text, image, or video. You can interact with resources (read, update, delete, etc) through dedicated endpoints or URLs for each resource.

Core Principles of REST APIs

Before an API qualifies as a REST API, some (or all) of these principles must be taken into account:

  1. Statelessness: A REST API has to be stateless. This means that all the requests sent from a client application (think frontend, for ease) must contain all the information required to process that request.
    A REST API will not retain any knowledge of previous requests or client sessions even if they are from the same client—it uses the data provided in the current request to respond.. Each request sent to a REST API must be independent of any other request.

  2. Client-Server Architecture: A client-server architecture is a model where tasks are divided between two main components: clients and servers. Typically, a client sends a request to a server and the server sends back a response.
    This model makes it possible for both the client and server to scale properly and independently; for example, you can change the entire user interface (client) without affecting the server or scale up the server without disrupting the client. A REST API must have a client-server architecture.

  3. Cacheability: The data or response provided by a REST API should be cacheable by the client or intermediaries. This simply means the client can store the information sent by the server and use it later instead of making a new request.

  4. Layered System: A REST API allows intermediaries, such as load balancers and proxies, to be inserted between the client and server without affecting the interaction. This makes the system more secure and scalable by distributing the load or filtering malicious requests.

  5. Uniform Interface: This feature requires all REST APIs to have a standardized way of doing things. REST APIs must use the common HTTP methods to grant access to a resource and also use a standard format such as JSON or XML to present resources.
    Things like naming conventions of endpoints and responses must be consistent and easy to understand.

HTTP Methods in REST APIs

An HTTP method or HTTP verb is a request method that tells the server the kind of action a client wants to perform on a resource. Every request sent to a REST API must contain an HTTP method.

REST APIs regularly use the following methods:

  1. GET: The GET method tells the server to retrieve or get a specific resource. For example, in a blog website, you can use the GET method to view a list of articles or a single article.

  2. POST: The POST method informs the server that the client wants to create a new resource. In modern applications, this can be anything from registering a new user to creating a post on social media. This new resource is stored on the server and can be viewed/retrieved with a GET method/request.

  3. PUT/PATCH: Both PUT and PATCH methods means the client wants to update a resource on the server. The PUT method allows the client to update the entire resource while the PATCH method allows the client to update small parts of the resource as it pleases. For example, updating a user profile or editing a blog post will use one of these methods.

  4. DELETE: The DELETE method simply means the client wants to remove a resource from the server.

JSON as the Standard Format for REST APIs

JSON stands for JavaScript Object Notation and despite its name, it is language angostic. This means JSON can be utilized in multiple programming languages without any issues. JSON is widely preferred over XML and other formats for REST APIs, because of its lightweight structure and ease of use.

Compared to XML, JSON typically results in smaller file sizes, which can lead to faster parsing and transmission. Additionally, JSON’s syntax is simple and easy to read, making it a more user-friendly option for developers.

Here is an example of a JSON object representing a person’s information:

{
  "firstName": "John",
  "lastName": "Doe",
  "age": 30,
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "postalCode": "12345"
  },
  "phoneNumbers": [
    {
      "type": "home",
      "number": "123-555-5555"
    },
    {
      "type": "work",
      "number": "123-555-5556"
    }
  ]
}

In the example above, you can observe the following:

  • The JSON object contains keys such as firstName, lastName, age, address, and phoneNumbers.

  • The value of address is another object (nested JSON object).

  • The value of phoneNumbers is an array of objects.

REST API Endpoints

In API development, endpoints are the URLs through which clients can interact with resources on a server.

Endpoints ensure the client and server are properly connected and handles the transfer of data between them.

A good API should always have clean, intuitive, and consistent endpoints that make it easy for developers to use and understand. REST API Endpoints usually follow a predictable and hierachical structure to represent resources and their relationships. Here are some examples for an ecommerce application:

  • api/products/all - to retrieve a list of all the products in the application using a GET method.

  • api/products/:id - to retrieve a single product (GET method) using its unique ID.

  • api/products/create - to create a new product in the application using a POST method.

  • api/products/:id/update - to update an existing product using its unique ID with a PUT or PATCH method.

Conclusion

This article has explained the basic concepts of RESTful APIs and how they are very useful and easy for developers to implement. Although there are more advanced concepts, understanding the basics of REST APIs will give you an edge when you start creating or consuming APIs for your application.

If you enjoyed this article, like share and comment!

APIsREST APIRESTful APIsendpointsapi