Requests

We have the endpoints. Now we decide what a request to each one looks like. There are three parts to decide: the HTTP method, the query parameters, and the headers.

The method is GET for every endpoint. The API is read-only: every request reads a resource. HTTP has other methods for creating, changing, and deleting a resource. This API does not use them.

A GET request has no body. Everything the server needs is in the request line and the headers. Here is the request for one course:

GET /api/courses/EN.601.226 HTTP/1.1
Host: registrar.university.edu
Accept: application/json

The request line carries the path, including the /api prefix from the base URL. The Host header carries the domain name. The Accept header says the client wants JSON back.

Here is a search:

GET /api/courses?search=data%20structures HTTP/1.1
Host: registrar.university.edu
Accept: application/json

The search string was “data structures”. A URL cannot contain a space, so the client replaces it with %20 before sending. This is URL encoding. Every character that has a meaning in a URL, such as ?, &, =, /, and the space, is replaced with a percent sign and its code when it appears inside a value. The server decodes it and searches for “data structures”.

Here is a request for offerings narrowed two ways:

GET /api/offerings?term=fall-2026&course=EN.601.226 HTTP/1.1
Host: registrar.university.edu
Accept: application/json

The two parameters are joined with &. The order does not matter. The server reads each one by name.

There is one thing a request may need to carry that we have not decided: who the client is. The fairness requirement says a registered client, such as CourseTracker, gets more requests per minute than an unknown one. For that to work, a request from CourseTracker has to say it is from CourseTracker. Where that goes, and what it looks like, is part of how the API limits requests, and we decide it there. It will be a header, because it is information about the client, not about the resource.