Created
September 8, 2026 05:05
-
-
Save Anthgg/9bd24ce73e5527ad9c9e875a4b03d762 to your computer and use it in GitHub Desktop.
BountyBook rest_best_practices.json deliverable
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| [ | |
| { | |
| "practice": "Use resource nouns in paths and let HTTP methods express the action.", | |
| "category": "url-design", | |
| "good_example": "GET /users/123", | |
| "bad_example": "GET /getUser?id=123", | |
| "rationale": "Resource-oriented paths make APIs predictable because the verb is already carried by the HTTP method.", | |
| "http_methods_involved": ["GET", "POST", "PUT", "PATCH", "DELETE"], | |
| "references": ["RFC 9110 HTTP Semantics", "Roy Fielding REST dissertation"] | |
| }, | |
| { | |
| "practice": "Use HTTP methods according to their standard semantics.", | |
| "category": "http-methods", | |
| "good_example": "DELETE /sessions/current", | |
| "bad_example": "GET /deleteSession/current", | |
| "rationale": "Correct method semantics help clients, caches, proxies, and observability tools understand safety and idempotency.", | |
| "http_methods_involved": ["GET", "POST", "PUT", "PATCH", "DELETE"], | |
| "references": ["RFC 9110 HTTP Semantics"] | |
| }, | |
| { | |
| "practice": "Version public APIs with an explicit, documented compatibility policy.", | |
| "category": "versioning", | |
| "good_example": "GET /v1/invoices/INV-123", | |
| "bad_example": "GET /invoices/INV-123 with unannounced breaking response changes", | |
| "rationale": "Explicit versions let clients upgrade intentionally and avoid silent production breakage.", | |
| "http_methods_involved": ["GET", "POST", "PUT", "PATCH", "DELETE"], | |
| "references": ["Microsoft REST API Guidelines", "Google API Improvement Proposals"] | |
| }, | |
| { | |
| "practice": "Return consistent machine-readable error bodies with stable codes.", | |
| "category": "error-handling", | |
| "good_example": "HTTP 422 {\"code\":\"invalid_email\",\"message\":\"Email is invalid\",\"field\":\"email\"}", | |
| "bad_example": "HTTP 200 {\"success\":false} or plain text 'bad request'", | |
| "rationale": "Stable error shapes let clients handle failures programmatically without parsing prose.", | |
| "http_methods_involved": ["GET", "POST", "PUT", "PATCH", "DELETE"], | |
| "references": ["RFC 9457 Problem Details for HTTP APIs"] | |
| }, | |
| { | |
| "practice": "Require authentication on private resources and authorize every object access server-side.", | |
| "category": "auth", | |
| "good_example": "GET /accounts/acc_123 with bearer token plus account membership check", | |
| "bad_example": "GET /accounts/acc_123 guarded only by a logged-in cookie", | |
| "rationale": "Authentication identifies the caller; authorization must also prove the caller can access the specific resource.", | |
| "http_methods_involved": ["GET", "POST", "PUT", "PATCH", "DELETE"], | |
| "references": ["OWASP API Security Top 10 2023"] | |
| }, | |
| { | |
| "practice": "Paginate collections with bounded limits and stable cursors.", | |
| "category": "pagination", | |
| "good_example": "GET /orders?limit=50&cursor=eyJpZCI6...", | |
| "bad_example": "GET /orders returning every order in one response", | |
| "rationale": "Bounded cursor pagination protects latency and memory while keeping results stable as data changes.", | |
| "http_methods_involved": ["GET"], | |
| "references": ["Google API Improvement Proposal AIP-158 Pagination"] | |
| }, | |
| { | |
| "practice": "Use caching, conditional requests, and compression for expensive or frequently read resources.", | |
| "category": "performance", | |
| "good_example": "GET /catalog/products with ETag, Cache-Control, and gzip or br compression", | |
| "bad_example": "GET /catalog/products recomputes the full response on every request with no cache headers", | |
| "rationale": "HTTP caching and compression reduce server load, bandwidth, and client wait time without changing API semantics.", | |
| "http_methods_involved": ["GET", "HEAD"], | |
| "references": ["RFC 9111 HTTP Caching", "RFC 9110 HTTP Semantics"] | |
| }, | |
| { | |
| "practice": "Publish an OpenAPI description with examples for successful and failing calls.", | |
| "category": "documentation", | |
| "good_example": "OpenAPI path /payments includes request schema, 201 response, 400 validation error, and auth requirement", | |
| "bad_example": "A README lists endpoints but omits schemas, error responses, and authentication details", | |
| "rationale": "Complete API descriptions make clients easier to generate, test, and keep compatible over time.", | |
| "http_methods_involved": ["GET", "POST", "PUT", "PATCH", "DELETE"], | |
| "references": ["OpenAPI Specification 3.1.0"] | |
| } | |
| ] |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment