Designing a REST API
This chapter designs a public, read-only API for a university’s course catalog, so that CourseTracker can read the registrar’s data instead of copying it in by hand. It starts with why CourseTracker needs the API and what the API must do, then covers the vocabulary of HTTP: clients and servers, URLs and endpoints, requests and responses. It then makes the design decisions one at a time: the resources, the endpoints, the shape of a request, the shape of a response, and the status codes.
After reading this chapter, you should be able to:
- Explain why one system should reach another system’s data through an API rather than a direct database connection
- Write functional requirements, quality attributes, and constraints for an API
- Define client, server, request, response, HTTP, REST, resource, and representation
- Name the parts of a URL and read an HTTP request and response line by line
- List the decisions an API designer makes and explain why a RESTful HTTP API fits a public, read-only catalog
- Derive resources from functional requirements and decide what is a resource of its own and what is part of another resource’s representation
- Write the endpoint for a collection and for an individual item, and decide what goes in the path and what goes in a query parameter
- Write a full HTTP request, including URL-encoded query parameters
- Write the JSON representation of a resource and choose field names and types
- Choose the status code and error body for each way a request can succeed or fail