Learning API Styles

Chapter 5. REST

Representational State Transfer (REST) is the most popular network-based API.¹ The REST architectural style² was formulated in 2000 by Roy Fielding in his Ph.D. dissertation “Architectural Styles and the Design of Network-Based Software Architectures”, as an approach to create internet-scale network-based applications.

This chapter goes through the origins, implementation, testing, security, documentation, and trade-offs of REST APIs. You’ll implement a REST API by using the Django REST Framework (DRF), for the Weather Forecast Service (WFS), introduced in “Weather Forecast Service”.

HTTP, Resource, and URI

In practice, the architectural goals of REST translate into three main components: HTTP, a resource, and a URI.

HTTP is the blood vessel of the internet, and the majority of API styles described in this book use HTTP to exchange messages. It’s supported by clients such as web browsers, command-line tools like curl, and libraries for various programming languages. HTTP is an application layer protocol that can be text-based or binary.³ You can find more details about HTTP in Chapter 4.

In REST, any information that can be named can be a resource—for example, a document, an image, a numerical value of zero, or even a person (a human being, a nonvirtual named entity not accessible via the internet).⁴ A resource is anything that can be a target of a hypertext reference.⁵

A resource can be static or dynamic. A static resource is immutable, like an image served from ...