The API Designer’s Job

We have the requirements, the vocabulary, and the basic concepts in place. Let’s talk about your job as a software designer for the registrar’s API. In short, your job is to make a set of decisions that together define the API. The requirements tell you what the API must do and how well it must do it. Your job is to decide how it will do it. Assuming you choose a RESTful HTTP API, your job is to decide what resources the API exposes, what endpoints it has, what requests and responses look like, etc.

Let’s go over some of the decisions you will make.

• What resources the API exposes, and what each is named. The requirements talk about terms, subject areas, courses, offerings, and professors. You decide which of these are resources of their own and which are carried inside another resource’s representation. The professor is one such decision: a resource with its own endpoint, or a few fields inside an offering.
• The endpoint for each resource. Every resource needs a URL. You decide the paths, and which filters and searches go in the path and which go in query parameters.
• What a request looks like. For each endpoint, which HTTP method the client uses, which query parameters it may send, and which headers matter.
• What a response looks like. The format of the body, which for us is JSON. The representation of a course and the representation of an offering, with the names and types of their fields. The status code for success. The status code and body for each way a request can fail, such as an unknown course number or a bad query parameter.
• How the API performs under load and over time. How a long list is cut into small chunks. Whether a response may be cached, and for how long. How many requests a client may send, and what response it gets when it has sent too many. How the API changes without breaking clients that have not changed. How a developer learns all of the above from the documentation alone.

Why a RESTful HTTP API

One decision comes before all of the others: the style of the API. I said earlier that we would design a RESTful HTTP API. Here is why it fits the requirements.

The API is public. We do not know who the clients are or what language they are written in, and we cannot hand each of them a library or a shared definition of the API. A RESTful HTTP API needs neither. Anything that can send an HTTP request can use it, including a browser, a command-line tool, and every programming language, and HTTP is already there in all of them.

The API is read-only, and the data changes slowly. A client sends a request when it wants something and gets a response. Nothing has to be pushed to a client, and no connection has to stay open between requests.

The same request from many clients returns the same response. A request for the offerings in Fall 2026 is the same request whoever sends it, and so is the response, until the registrar changes the catalog. Responses like that can be cached, which is what the freshness requirement allows for.

The requirements list a few collections with a few ways to filter each. A fixed set of endpoints, each with its own URL, covers all of them. No client needs to write its own query, and the registrar’s office can see every request the API can receive by reading the list of endpoints.

There are other kinds of API, and we will study some of them later in the course. Once we have studied them, you will see more clearly why these requirements point to this decision.