Server-Side Functionality with a Database

RESTful API Design

---

One of the most common ways of implementing APIs in web applications is following Representational State Transfer (REST). REST is not a formal standard, but rather a set of constraints or guidelines.

REST was originally discussed in Roy Fielding’s PhD thesis Architectural Styles and the Design of Network-based Software Architectures, which everyone interested in web software development should (at least) skim through.

The REST guidelines have been used as a set of guiding principles for designing “RESTful APIs” that are easy to understand and use.

Features of RESTful APIs

Presently, RESTful APIs (often just called REST APIs) are mostly understood as having the following features. In Fielding’s original formulation, REST also emphasizes cacheability, a layered system, and a uniform interface, but in practice many introductions (like here) focus on the core features below:

• HTTP-based client-server architecture: APIs use client-server architecture, where the client and the server are separated from each other and requests are made over HTTP.

• Stateless communication: APIs are stateless, which means that each request is independent of the previous request and that the server does not have to keep track of the clients or the requests.

• Identifiable resources: APIs are about resources (e.g. documents, images, time-based data, …) that have identifiers. In the context of RESTful APIs, the identifiers are URIs.

• Representable resources: The resources are represented in a format that is suitable for the client. Currently, the most common format is JSON.

• Manipulation of resources through representations: The resources can be manipulated through representations and their identifiers, i.e. a client can send a representation of the resource (e.g., a JSON document) to an address that identifies a resource (e.g., an URI), which the server can use to manipulate (e.g., update) the resource.

• Self-descriptive messages: The messages that are sent between the client and the server are self-descriptive, i.e. they contain the information that is needed to understand the message. In the context of web applications, this typically includes using HTTP methods and status codes.

Loading Exercise...

API design and REST

Most contemporary RESTful APIs use HTTP as the communication protocol, which is stateless by design. Resources are identified using URIs, and standard HTTP methods such as GET, POST, PUT, and DELETE are used to manipulate resources. Other methods like PATCH or OPTIONS can also be part of a RESTful API when appropriate.

As an example, our earlier book application follows RESTful design principles. The application has a resource, which is a book, and the API allows manipulating the book resource using HTTP methods.

• GET /api/books: Retrieve all books and return the books in JSON format.
• POST /api/books: Using JSON data from the request body, create a new book.
• GET /api/books/:bookId: Retrieve a book with the given id and return the book in JSON format.
• PUT /api/books/:bookId: Using JSON data from the request body, update the book with the given id.
• DELETE /api/books/:bookId: Delete a book with the given id.

Loading Exercise...

APIs can also have more complex structures. For example, if we wanted to extend our book application to include chapters for each book, we could design the API to reflect this relationship.

Such an API could also have endpoints for retrieving chapters of a book, creating a new chapter for a book, updating a chapter, and deleting a chapter. For this, a hierarchical structure could be used, where the books and chapters are related to each other, as outlined below.

• GET /api/books/:bookId/chapters: Retrieve all chapters for a book with the given id and return the chapters in JSON format.
• POST /api/books/:bookId/chapters: Using JSON data from the request body, create a new chapter for a book with the given id.
• GET /api/books/:bookId/chapters/:chapterId: Retrieve a chapter with the given chapterId for a book with the given id and return the chapter in JSON format.
• PUT /api/books/:bookId/chapters/:chapterId: Using JSON data from the request body, update a chapter with the given chapterId for a book with the given id.
• DELETE /api/books/:bookId/chapters/:chapterId: Delete a chapter with the given chapterId for a book with the given id.

Loading Exercise...

In the next chapter, we’ll implement this concretely, extending our book application so that each book includes chapters.

Summary

In summary:

• REST (Representational State Transfer) is an architectural style that defines guidelines for designing APIs.
• Contemporary RESTful APIs are typically HTTP-based, stateless, and resource-oriented.
  • The resources are identified by URIs and represented in formats such as JSON.
  • Resources are manipulated by sending representations (e.g., JSON documents) using standard HTTP methods like GET, POST, PUT, and DELETE.
  • Messages are self-descriptive, making use of HTTP methods, status codes, and headers to convey meaning.