Business Rules - API Design

This document lists the fundamental business rules of the API Design domain, identified with unique codes BR-NNN. Each rule is technology-independent and describes an invariant constraint on system behaviour.

---

BR-001 - Rate Limiting mandatory on every public endpoint

Code: BR-001 Name: Rate Limiting mandatory on every public endpoint Description: Every publicly exposed endpoint must apply a frequency limit to protect server resources and ensure fairness among clients. The limit may vary by plan (free/pro/enterprise) but must never be absent. Rationale: Prevent abuse, Denial-of-Service and unfair consumption of shared resources. Priority: HIGH Actors: Rate Limiter, API Gateway Violation: HTTP 429 Too Many Requests with Retry-After header. Traceability: RFC 9110 §15.5.29; OWASP API4:2023.

---

BR-002 - Idempotency of safe mutation operations

Code: BR-002 Name: PUT, PATCH and DELETE operations must be idempotent Description: Executing the same mutation operation multiple times with the same input must produce the same effect as executing it once. Clients must be able to retry safely on network timeouts without fear of unintended side effects. Rationale: Ensure robustness against network failures and retransmissions. Priority: HIGH Actors: Client, Resource Server Exceptions: POST is usually NOT idempotent; use Idempotency-Key header to make it idempotent. Traceability: RFC 9110 §9.2.2.

---

BR-003 - Explicit versioning before breaking changes

Code: BR-003 Name: A breaking change requires a MAJOR version increment Description: Any change that breaks compatibility with existing clients (field removal, semantic change, validation tightening) must be released on a new MAJOR version of the API. The previous version must remain operational for the established deprecation period. Rationale: Protect clients from unexpected regressions; honour the implicit stability contract. Priority: HIGH Actors: API Gateway, Resource Server Traceability: SemVer 2.0.0; Google AIP-180.

---

BR-004 - Authentication mandatory on non-public resources

Code: BR-004 Name: Every non-public resource requires a valid access token Description: Requests to protected endpoints must present an access token (e.g. JWT, OAuth 2.0 Bearer Token) in the Authorization header. The server must verify signature, expiry and scope before processing the request. Rationale: Prevent unauthorised access to sensitive data or operations. Priority: CRITICAL Actors: Auth Service, API Gateway Violation: HTTP 401 Unauthorized for missing/expired token; 403 Forbidden for insufficient scope. Traceability: RFC 6749; RFC 7519; OWASP API1:2023.

---

BR-005 - Pagination mandatory for unbounded collections

Code: BR-005 Name: Collection resources must support pagination with a configurable maximum limit Description: Every endpoint returning a list of resources must support pagination (offset or cursor). The maximum number of items per page (page_size) has a server-defined ceiling (e.g. 100); requests beyond the limit are truncated or rejected with 400 Bad Request. Rationale: Prevent memory exhaustion, timeouts and bandwidth abuse. Priority: HIGH Actors: Client, Resource Server Traceability: Google AIP-158; RFC 9457 (error format).

---

BR-006 - Error contract - uniform structured format

Code: BR-006 Name: All error responses must follow a uniform structured format Description: Error bodies must include at least: problem type (type), human-readable title (title), HTTP status code (status), textual detail (detail) and request instance (instance). No internal detail (stack trace, SQL query, file path) must leak to clients. Rationale: Facilitate programmatic error handling; avoid sensitive information disclosure. Priority: HIGH Actors: Resource Server, API Gateway Traceability: RFC 9457 (Problem Details for HTTP APIs).

---

BR-007 - Deprecation with minimum advance notice

Code: BR-007 Name: A deprecated endpoint must announce deprecation at least 90 days before removal Description: When an endpoint is deprecated, the server must return the Deprecation header (RFC 8594) with the removal date. Documentation must be updated and clients notified via changelog and/or email at the time of deprecation. Rationale: Give clients time to migrate without service interruptions. Priority: MEDIUM Actors: Resource Server, Client Traceability: RFC 8594; RFC 9745 (Sunset).

---

BR-008 - Mandatory TLS on all endpoints

Code: BR-008 Name: All communication between client and server must occur over TLS 1.2+ Description: The API must not accept plaintext connections (HTTP). Every endpoint must require TLS 1.2 at minimum; TLS 1.3 is preferred. Redirects from HTTP to HTTPS are acceptable but do not replace direct rejection of unencrypted connections. Rationale: Protect authentication tokens, data in transit and guarantee communication integrity. Priority: CRITICAL Actors: API Gateway, Client Traceability: OWASP API2:2023; RFC 9110 §4.2.2.