Documentation

The usability requirement says a developer who has never talked to the registrar’s office must be able to make a first successful request from the documentation alone. The documentation is where we write down everything we decided in this chapter, in a place a developer can find. It is a web page. I put it at https://registrar.university.edu/api, one level above the versioned base URL, so a developer who has the URL of the API also has the URL of its documentation.

What it contains

The documentation lists the decisions from this chapter, in the order a developer needs them.

  • The base URL, with the version number, and the retirement date of each version that is still running.
  • How to get an API key, and that a request without one gets the lower rate limit.
  • Every endpoint, with the query parameters it accepts and the values each parameter accepts. For term and subject_area, the documentation says the values come from the terms and subject areas endpoints.
  • Example responses for each resource type, including collections and individual items where supported, so a developer can see every field, its name, and its type.
  • The paging parameters, their defaults, and the maximum page size.
  • Every status code the API returns, when it returns each one, and the shape of the error body.
  • The caching headers and the one-hour time to live.
  • The rate limits for each tier and what a 429 response looks like.

The first request

The requirement is about a first request, so the documentation starts with one. Before any of the list above, the page shows one complete request and its response, the way the requests section of this chapter did:

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

A developer copies that request into whatever tool they use, sends it, and gets a course back. After that, the developer reads the rest of the page to learn what else the API does.

The documentation is part of the API

Developers write a client from the documentation. They do not read the server’s code. When CourseTracker’s developers read that credits is a number, they write code that treats it as a number. If the documentation says it is a string, they write the wrong code, even though the server is sending a number. So the documentation is part of what the registrar’s office commits to. A change to the API is not finished until the documentation says the same thing the server does.

Also, each version of the API must have its own documentation. Each version’s documentation must link to the version before it and the version after it, so a developer can see what changed. You should also give a migration guide that lists the breaking changes and how to handle them.

There is a standard format for writing down an API’s endpoints, parameters, and representations. It is called OpenAPI. Tools can read it to generate the documentation page, to test the server against the documentation, and to generate client code. You are not expected to write OpenAPI in this course, but you should know that it exists.