Treat the API as a long-lived contract
A browser, mobile client and partner integration may consume the same API for years. Write a contract that defines resources, methods, error shapes, pagination, identity, rate limits and compatibility policy. A path such as /api/v1/orders/ should reflect meaningful resource behavior, not mirror internal ORM model names indiscriminately. Keep backward-incompatible representation changes behind explicit versions or coordinated client migrations. Support deprecation with published timelines and instrumentation showing whether old clients still operate.
Correct HTTP semantics reduce ambiguity
GET should retrieve without causing a business mutation; POST creates or starts an operation; PUT normally replaces a resource; PATCH applies a partial change whose semantics must be documented; DELETE has an idempotent target effect even if subsequent response codes vary. Return 201 and a resource location when a synchronous create succeeds, 202 for accepted asynchronous processing, 409 for a state conflict and 422 where a well-formed payload violates semantic validation rules in an API that uses that distinction. Status codes cannot repair an undocumented state machine.
Idempotency is essential for money and fulfillment
Network retries are routine: the client may time out after the server has already committed an order. For a create operation with side effects, an idempotency key can identify repeated requests. Scope the key to authenticated principal, operation and relevant payload fingerprint, store the outcome transactionally, and reject reuse with a conflicting payload. Apply a documented retention policy rather than keeping every key forever. An idempotency key does not replace unique database constraints, settlement deduplication or careful treatment of genuinely new customer orders.
Optimistic concurrency and lost updates
Two editors can load the same document and submit different changes. Last-write-wins silently loses information unless that policy is intentional. Use an entity version or strong ETag as a concurrency token; require an If-Match precondition on updates when appropriate, and return 412 if the submitted version no longer matches. Compare version and persist change atomically. Weak ETags may suit caching but not all update preconditions. Document how clients retrieve the current state and reconcile a conflict rather than automatically overwriting another user's work.
Object-level and field-level authorization
Authentication answers who made the request; authorization answers whether that actor may perform a particular operation on a particular resource and its fields. Filter querysets by tenant or ownership before retrieving user-facing objects where feasible, and verify the permission again at mutation boundaries. Prevent mass assignment: a normal user must not be able to set is_staff, settled or published fields merely because the serializer accepts them. OWASP ASVS 5.0 explicitly emphasizes function, object and field-level checks.
Pagination, ordering and filtering correctness
Offset pagination is simple but can skip or duplicate items while new records are inserted. Cursor pagination with a stable, unique ordering key is often preferable for fast-changing feeds. Define maximum page size, allowed filters and query budgets, and ensure database indexes support common predicates. Expose consistent timestamps in a documented format. Do not leak forbidden item counts through search or pagination metadata. A filter that creates unrestricted wildcard queries may become an application-level denial-of-service vector.
Observability, rate limiting and practical API tests
Return a stable error envelope with a machine-readable code, brief message and request identifier. Never expose stack traces, passwords or internal connection strings. Monitor p95 latency, 4xx/5xx distributions, idempotency conflicts and downstream dependency timeouts. Apply meaningful quotas per identity and operation, with explicit handling of client retries and 429 responses. Tests should cover cross-tenant access, invalid transitions, duplicate requests, simultaneous updates, malformed pagination, credential expiry and clock skew. References: https://www.rfc-editor.org/rfc/rfc9110 and https://owasp.org/www-project-application-security-verification-standard/ .
Editorial disclosure: Original advanced educational content by Mojtaba Roozegar. Examples are illustrative, not an audit of a particular production deployment or a guarantee of outcomes. Relevant external technical references are linked within each article.