RESTful API Design
Introduction REST (Representational State Transfer) working with JSON over HTTP/1.1 or HTTP/2 remains the default choice for public APIs and B2B integrations due to its popularity, debuggability and broad ecosystem. API Design & Resource Modeling When adopting REST , the design must maintain consistency, including the following characteristics: Resource-oriented Use plural nouns ( /api/v1/orders, /api/v1/users ). Placing actions in the URL, such as /orders/{id}/cancel , is a bad practice. Instead, use POST /orders/{id}/cancellations or PATCH /orders/{id} with a payload that updates state. Idempotency Ensure GET, PUT, DELETE are always idempotent. For POST (creating resources or processing payments), enforcing an Idempotency-Key in the Header is mandatory to prevent duplicate transactions during network glitches and client retries. Versioning Implement versioning from day one. Prefer URL Versioning (/api/v1/...) because it is explicit, easy to route at the Gateway layer (Nginx...