Requirements for the API

Before we design the API, we need to say what it must do and how well it must do it. This is the same step chapter 1 took for HopPress. The registrar’s office is the stakeholder that owns the data. CourseTracker is the first consumer. Other developers who build on the same data are consumers too but we do not know who they are.

Functional requirements

The requirements below use these terms based on the registrar’s catalog:

  • A term is an academic period such as Fall 2026.
  • A subject area is a grouping of courses such as Computer Science, the same grouping chapter 2 used.
  • A course is a course as it appears in the catalog, such as EN.601.226 Data Structures, whether or not it is offered this term.
  • An offering is one course taught in one term by one professor, at a meeting time, in a room.

The API must satisfy these functional requirements:

  • When a client requests the list of terms, the API must return every term the catalog covers.
  • When a client requests the list of subject areas, the API must return every subject area.
  • When a client requests the list of courses, the API must return them. The client must be able to narrow the list to one subject area, and to search it by course number or by title.
  • When a client requests one course by its course number, the API must return its number, title, credits, and subject area.
  • When a client requests the list of offerings, the API must return them. The client must be able to narrow the list to one term, to one subject area, or to one course, and to search it by course title or by professor name.
  • When the API returns an offering, it must include the course number, title, and credits, the term, the professor’s name and university email address, the meeting time, and the room.

The last requirement is the one that matters most to CourseTracker.

Note that the API is read-only. We only read the registrar’s data, never write to it. Data changes still happen inside the registrar’s own system, by the people who run it.

System quality attributes

The API must also meet these requirements for system quality attributes:

  • Performance: When a client requests one course, one offering, or one page of a list, the API must return the response in under one second.
  • Response size: No single response may be larger than one megabyte. A client must be able to get the whole catalog, but not in one response.
  • Freshness: The data the API returns may be at most one hour behind the registrar’s system.
  • Availability: During each calendar month, clients must be able to read the catalog at least 99.9 percent of the time. This is the same target chapter 1 set for HopPress, and it allows the same 43 minutes of unavailability in a 30-day month.
  • Isolation: Traffic to the API must not slow down the registrar’s own work. However many requests arrive, the people entering courses and scheduling offerings must not notice.
  • Fairness: A registered university system, such as CourseTracker, must be allowed more requests per minute than a caller the university does not know. The exact limits are a design decision, but the two tiers are a requirement.
  • Compatibility: A change to the API must not break a client that has not changed. CourseTracker must keep working when the registrar adds a field, and it must be told before a field goes away.
  • Usability: A developer who has never talked to the registrar’s office must be able to make a first successful request from the API’s documentation alone.

Each of these is a measurable target. We will design toward each one as we go, and each will push the design in a specific direction.

System constraints

The API must also respect these system constraints:

  • Technical: The API must run on the registrar’s existing hosting platform, next to the registrar’s system.
  • Technical: All traffic to the API must be encrypted.
  • Legal: The API must not expose anything about a professor beyond what the university’s directory already publishes, which is name and university email. (E.g., no personal contact information.)
  • Legal: The API must not expose student data of any kind. Registration, seats, waitlists, grades, and degree audits are out of scope.

These constraints are especially important because the API is public. With a private API for CourseTracker alone, the registrar could agree with its developers on what data they receive and how they use it. A public API cannot rely on such agreements with its unknown consumers. Whatever it returns, it returns to everyone, so these limits have to be built into the API itself.