API foundations
Design the Books API
Turn a small product requirement into resources, representations, routes, and a stable HTTP contract before writing handlers.
8 minute lesson
An API is an interface between programs. Our project is a Books API that lets clients list, create, read, update, and delete books.
Model nouns as resources and use HTTP methods to express common actions. Start with /books and /books/:id. Write one example JSON representation and the expected response status for each operation before choosing database code.
The contract is more than route names. Decide which fields the client may send, which fields the server owns, whether an update replaces or partially changes a book, and what an empty collection looks like. Keep one stable representation shape so clients do not need route-specific guesses.
Write a small behavior table before implementation: method and path, input, successful status, response body, and expected errors. Include GET /books, POST /books, GET /books/:id, PUT /books/:id, and DELETE /books/:id. This table becomes the basis for tests and OpenAPI later. If a handler decision cannot be traced to the table, the contract is still incomplete.
Sketch the five routes, one book representation, and the error response for an unknown book.
Lesson completed