Resources

Start with the functional requirements. Each one says what a client can request: the list of terms, the list of subject areas, the list of courses, one course, and the list of offerings. Each of these requests is for something. That something is a resource.

Look at courses. A client can request the collection of courses, and it can request one course. The collection is a resource, and each individual course is also a resource. Offerings work the same way. Terms and subject areas are different. A client can request all of the terms, but nothing in the requirements requests one term on its own. There is nothing to say about one term beyond its name, and the full list already has the name. Subject areas are the same.

So the API is organized around four resource types: terms, subject areas, courses, and offerings. We name a collection with a plural noun. We do not name a collection with a verb. There is no “search” resource. A client searches by sending a request for courses with a query parameter on it.

The professor is the one decision that takes some thought. No requirement requests a professor. The requirements request offerings, and they say each offering comes with its professor’s name and email. So the professor is not a resource of this API. It is part of an offering’s representation. We could have made it a resource, and it would have worked. I left it out for two reasons. First, no requirement needs it. If a client wants everything a professor teaches, it narrows the offerings by professor name, and that is already in the requirements. Second, the privacy constraint says the API must not expose anything about a professor beyond name and email. That is easiest to keep when the API has no place where a professor is the subject.

If a client can request an individual item, that item needs an identifier. That is the value the client puts in the request to say which one it wants. For a course, the identifier is the course number, such as EN.601.226. Chapter 2 made the course number the primary key for the same reasons: the registrar assigns it and it does not change. For an offering, I assume the registrar’s system already has an identifier for each one, and the API exposes that. It does not matter what it looks like. It matters that it stays the same for as long as the offering exists.

Here is the summary of the design decisions we have made about the resources of the API: