Designing a Write API

This chapter designs an API for a notes app, so that clients can create, change, and delete data, not only read it. It starts with the app and what its API must do. Then it makes the design decisions one at a time: the resource and its endpoints, the request that creates a note, the requests that replace or change one, and the request that deletes one. It ends with what a client should do when a request gets no response, and why some requests can be sent again without repeating their effect while others cannot.

After reading this chapter, you should be able to:

• Explain why a notes app needs an API and state its requirements
• Identify the resource and write its collection and item endpoints
• Name the HTTP methods for creating, reading, replacing, changing part of, and deleting a resource
• Write a request that creates a resource and read a 201 Created response with its Location header
• Distinguish replacing a resource with PUT from changing part of it with PATCH
• Write a request that deletes a resource and explain 204 No Content
• Explain why a timeout leaves the outcome of a write unknown
• Distinguish safe and idempotent requests, and say which methods are which
• Use an idempotency key so a POST can be sent again without repeating its effect

Sections

1. A Notes API
2. Resources and Endpoints
3. Creating a Note
4. Replacing and Changing a Note
5. Deleting a Note
6. Retrying a Request