Designing Endpoints

Start from use cases

List what clients must do—list books, create a book, publish a review—then map each to a method and path.

Example mini surface

GET    /api/books
POST   /api/books
GET    /api/books/{id}
PATCH  /api/books/{id}
DELETE /api/books/{id}
POST   /api/books/{id}/publish

Actions vs resources

When an action is not a clean CRUD update, a sub-resource or verb path can help (/publish). Prefer resource state when it stays clear.

Document examples

Show sample requests and responses early. Contract clarity saves more time than clever URL tricks.