Design an HTTP endpoint that is predictable to call and safe to change — resource-shaped URLs, honest status codes, useful errors, and pagination from day one. Use when adding an API endpoint or reviewing an API design.
--- name: design-an-api-endpoint category: coding description: >- Design an HTTP endpoint that is predictable to call and safe to change — resource-shaped URLs, honest status codes, useful errors, and pagination from day one. Use when adding an API endpoint or reviewing an API design. --- # Design an API Endpoint An API is a promise you cannot easily take back. Once someone integrates, every field is load-bearing and every quirk is permanent. An hour of design now is worth a year of deprecation notices later. ## Model resources, not actions URLs name **things**; the method says what you are doing to them. ``` GET /orders?status=pending list POST /orders create GET /orders/8891 read PATCH /orders/8891 partial update DELETE /orders/8891 remove ``` Not `/getOrders`, `/createOrder`, `/updateOrderStatus`. Those multiply forever and force the caller to learn each one. For genuine actions that are not CRUD, a sub-resource reads better than a verb in the path: ``` POST /orders/8891/refunds not POST /refundOrder POST /users/12/password-resets not POST /resetPassword ``` This has a practical payoff: the action becomes a thing with an id, which you can list, retry idempotently, and audit.
You are reading the opening of this skill.
The rest is open to any signed-in account — free included. Reading the library costs nothing.
Shared publicly by the author and open for any use. See the Terms.