RESTful API Basics

A Very Short Example

Author

Matthew Ryckman
August 17, 2024

There are a handful of architecture patterns for designing a networked application, such as a web app. Some of the more common ones include GraphQL, gRPC, WebSockets, and SOAP. By far, the most common is REST.

In this article, I’ll give a very brief introduction to REST to help you get started designing a RESTful API. I won’t cover any code, since REST is not tied to any specific language or technology. REST is a theoretical framework for building a networked application, which means you can use any programming language you want to try to implement an API that follows its standards.

REST

REST stands for Representational State Transfer. Building an entire RESTful API is far outside the scope of this article, but its important to understand its most basic concepts. There are six core principles to which a true REST API must adhere. When a REST API conforms to these standards, we say that the API is RESTful. When an API uses some of the principles of REST, but not all of them, then we say the API is REST-like.

REST Standards

  • Client-Server Architecture: This principle separates the user interface concerns (client) from the data storage concerns (server). This separation allows for independent development and deployment of the client and server components, leading to more scalable and flexible systems.

  • Statelessness: Each request from a client to a server must contain all the information needed to understand and process the request. The server does not store any client context between requests. This makes each request independent and simplifies server design, as no session information is stored on the server side.

  • Cacheability: Responses must define themselves as cacheable or non-cacheable, allowing clients to reuse the response data in subsequent requests. This can significantly reduce the number of interactions with the server and improve the scalability and performance of the system.

  • Uniform Interface: A standardized interface between clients and servers simplifies and decouples the architecture. This principle includes several constraints, such as using resource identifiers in requests (e.g., URLs), resource representations (e.g., JSON, XML), self-descriptive messages, and hypermedia as the engine of application state (HATEOAS).

  • Layered System: A layered system architecture allows an application to be composed of hierarchical layers by constraining component behavior. Each layer interacts only with the layer immediately next to it. This can improve system scalability and simplify interactions by allowing components to be replaced or updated without affecting the entire system.

  • Code on Demand (Optional): Servers can extend client functionality by transferring executable code. This is an optional constraint and is not used in all RESTful services. Examples include JavaScript or applets sent to the client to provide enhanced features or functionality.

A central concept in REST is the use of HTTP verbs to send requests to the API endpoints. As a simple example, consider a personal blog software that allows the user to create, read, update, and delete blog posts.

Blog Example

Suppose I want to make a blog application that lets a users manage articles for their personal blog. Articles are stored in a database and the user interacts with the articles via the frontend of the application. In general here’s what a very basic REST API for this application might look like.

Resource: Articles

Base URL for Resources: https://api.thethunderislandnavigator.net/articles

  1. GET /articles

    • Description: retrieve all the articles in the blog.

    • Usage: A client sends a request to this endpoint to fetch the articles.

    • Response: Returns a JSON response containing a collections of article objects to the client. The articles can be cached to reduce the number of requests to read from the database.

  2. GET /articles/{id}

    • Description: Retrieve a specific article matching the id value.

    • Usage: A client sends a request to this endpoint to fetch an article by a given id.

    • Response: Returns a JSON response containing a single article object to the client that matches the given id. The article can be cached to reduce the number of requests to read from the database.

  3. POST /articles

    • Description: Create a new article in the blog.

    • Usage: A client sends a request to this endpoint along with an object representation of the article.

    • Response: Returns a JSON response containing a status code matching the result of the request.

  4. PUT /articles/{id}

    • Description: Update an article that matches the id value.

    • Usage: Client sends a request to this endpoint along with the object representation of the modified article.

    • Response: Returns a JSON response containing a status code matching the result of the request.

  5. DELETE /articles/{id}

    • Description: Delete an article from the blog that matches the id value.

    • Usage: Client sends a request to this endpoint to delete the article.

    • Response: Returns a JSON response containing a status code matching the result of the request.

Notice that the requests to these endpoints center around basic requests using HTTP verbs to create, read, update, and delete articles. These are called CRUD operations and they make up most of the types of interactions users will have with an application’s data.

The API follows all the REST principles and is therefore a RESTful API.

  • Client-Server Architecture: The client communicates with the API to perform operations on articles.

  • Statelessness: Each new request to the API comes with all the necessary data for the server to handle the request without the need for the server to know the "state” of the application in between each request.

  • Cacheability: The responses from the GET requests can be cached to reduce trips into the database.

  • Uniform Interface: Only HTTP verbs are used to send requests to the API. Responses are returned in a consistent format, such as JSON. URLs follow a pattern that matches the requested resources.

  • Layered System: Although not represented here, the API can be structured in layers, with other components for handling critical operations, like authentication and logging, sitting in other layers. These functionalities are not tangled up with the endpoints for articles.

  • Code on Demand: This was not included in the example, but the API could return some scripts to the client to interact with the data. For example, a script could be sent back to filter articles based on draft vs. complete status.

Wrapping up

REST an architecture pattern for designing networked applications, like web apps. A RESTful API is a web API that follows the six core REST standards.

If you’re looking to get into web development as a software engineer, understanding REST well is one of the best ways to demonstrate your knowledge of the web.

This is one area where organizations struggle to build a quality web app, as they lack the fundamental knowledge of the REST pattern. As a result, their applications often are hard to extend and maintain when these standards are broken and many one-off solutions implemented throughout the code base.

If you or anyone you know wants to share their experience applying for jobs in the current job market, inside or outside software engineering, we encourage you to respond in an email to this newsletter! You may be featured in our next article.

Thank you for reading and we will see you in our next article as we continue our voyage.

Code on,
Matt, Editor and Software Engineer

Reply

or to participate.