RESTful HTTP API

We are going to design a RESTful HTTP API for the registrar’s course catalog. This is the most popular way for two systems to talk over the web. It uses HTTP (Hypertext Transfer Protocol), the same protocol a browser uses to load a page from a website. There are other ways to design APIs, and I will explain why this is the right one for the registrar’s API once we have laid out what designing an API involves. Before we get to the design part, we need to cover some basic concepts and terminology.

The usual way two systems interact over the web is that one sends a request and the other sends back a response. The one that requests is the client. The one that responds is the server. This structural arrangement is called the client-server model, and the interaction pattern is called the request-response cycle. Client and server are roles in one exchange, not kinds of system. CourseTracker is a client when it asks the registrar for offerings. It is a server when a browser asks it for a student’s course history.

The request and response adhere to a protocol, a defined shape and set of rules for how the two systems talk. The most popular request-response protocol for client-server communication over the web is HTTP. We will explore the structure of an HTTP request and response shortly.

REST (Representational State Transfer) is a set of principles for designing networked applications, originally created to guide the design of the web. A central idea is that the server sends a representation of a resource’s state when a client requests it. A resource is any piece of information that can be named, such as a course. A representation is the data that describes the resource at a given time, such as the number, title, and credits for a course.

In practice, developers often use “RESTful API” to mean an HTTP API organized around resources, using URLs to identify them and standard HTTP methods to interact with them. This common usage does not necessarily imply adherence to all of REST’s original principles. We will use the term in this practical sense and focus on the conventions for designing such APIs.