Principes de conception de l'API
Un guide concis sur l’ergonomie, la facilité de découverte et la cohérence des API, fondé sur des règles de conception communes et les besoins réels des consommateurs.
Comment cela fonctionne-t-il ?
Section intitulée « Comment cela fonctionne-t-il ? »- Consumer-first design: commencer chaque cycle APIOps en rassemblant les objectifs des utilisateurs et les termes du domaine afin que les APIs résolvent des problèmes réels.
- Noms et comportements cohérents: appliquer des conventions partagées pour les ressources, les erreurs et les formats afin de rendre les API prévisibles.
- Dirigé par le contrat: capturer l’interface avec OpenAPI ou AsyncAPI avant le codage pour aligner les équipes et permettre l’automatisation.
- Utilisabilité et facilité de découverte: fournir une documentation et des exemples clairs afin que les développeurs comprennent rapidement comment utiliser l’API.
- **Les conceptions évoluent par petites étapes et par versions, de sorte que les changements ne perturbent pas les consommateurs existants.
Guidelines
Section intitulée « Guidelines »| Id | Priority | Category | Requirement | Related audit items |
|---|---|---|---|---|
REST-CONTRACT-01 | MUST | contract-governance | The REST API MUST implement endpoints, parameters, request bodies, response bodies, and error responses as defined in the validated OpenAPI contract. | spec-contains-schemas, schema-and-examples-pass |
REST-CONTRACT-02 | MUST | contract-governance | The REST API MUST keep the implementation, published OpenAPI description, gateway configuration, and developer portal documentation aligned on every change. | docs-auto-generated, spec-auto-updated, spec-validated-on-change |
REST-VALIDATION-01 | MUST | contract-governance | The REST API MUST validate path parameters, query parameters, headers, and JSON request bodies against the OpenAPI schema before business processing. | mandatory-fields-specified, 400-errors-specific, inputs-auto-validated |
REST-DOMAIN-01 | MUST | domain-modeling | The REST API MUST expose business-oriented resources and attributes rather than raw backend tables, internal service payloads, or system-specific field names. | hides-raw-backend-data, design-consistent |
REST-DOMAIN-02 | MUST | domain-modeling | The REST API MUST preserve validated meanings of entities, attributes, statuses, and source-of-truth rules across all endpoints and operations. | design-consistent, general-data-uses-standard-values |
REST-NAMING-01 | MUST | domain-modeling | The REST API MUST use descriptive English names for resources and attributes. | descriptive-english-naming |
REST-NAMING-02 | MUST | domain-modeling | The REST API MUST avoid unexplained acronyms in public field and resource names. | field-names-avoid-acronyms |
REST-DATA-01 | MUST | domain-modeling | The REST API MUST use ISO date-time values with timezone information where dates are exposed. | dates-use-iso |
REST-DATA-02 | SHOULD | domain-modeling | The REST API SHOULD use standard codes, controlled vocabularies, and standardized value sets where applicable. | general-data-uses-standard-values |
REST-CX-01 | MUST | consumer-experience | The REST API MUST describe the business value and feature intent of each endpoint or capability. | endpoint-descriptions-present |
REST-CX-02 | MUST | consumer-experience | The REST API MUST include examples for endpoints, request bodies, response bodies, and key attributes. | examples-present |
REST-CX-03 | SHOULD | consumer-experience | The REST API SHOULD use consistent pagination, filtering, sorting, and response conventions across resources. | design-consistent |
REST-HTTP-GET-01 | MUST | http-semantics | The REST API MUST use GET for safe read-only operations and MUST NOT define a request body for GET operations. | get-no-request-body, http-methods-match-resources |
REST-HTTP-POST-01 | MUST | http-semantics | The REST API MUST use POST for resource creation and other non-idempotent operations. | post-for-create-update |
REST-HTTP-PUT-01 | MUST | http-semantics | The REST API MUST use PUT only for full resource replacement. | post-for-create-update, http-methods-match-resources |
REST-HTTP-DELETE-01 | MUST | http-semantics | The REST API MUST use DELETE to remove resources. | delete-for-remove, http-methods-match-resources |
REST-PATH-01 | SHOULD | resource-modeling | The REST API SHOULD keep endpoint paths shallow and avoid more than two resource or sub-resource levels unless explicitly justified. | paths-max-two-resources |
REST-RESP-200-01 | MUST | status-codes | The REST API MUST return 200 OK for successful reads and updates that include a response body. | get-no-request-body, post-returns-200 |
REST-RESP-201-01 | MUST | status-codes | The REST API MUST return 201 Created and the created resource identifier when a new resource is created. | create-returns-identifiers, post-returns-201 |
REST-RESP-204-01 | MUST | status-codes | The REST API MUST return 204 No Content for successful delete operations that do not return a body. | delete-returns-204 |
REST-RESP-204-02 | SHOULD | status-codes | The REST API SHOULD return 204 No Content for successful operations that intentionally return no response body. | get-empty-returns-204 |
REST-ERROR-400-01 | MUST | error-handling | The REST API MUST define 400 Bad Request responses with specific and actionable validation error information. | 400-errors-specific |
REST-ERROR-401-01 | MUST | error-handling | The REST API MUST return 401 Unauthorized for missing or invalid credentials. | 401-unauthorized |
REST-ERROR-403-01 | MUST | error-handling | The REST API MUST return 403 Forbidden for authenticated clients lacking sufficient permission. | 403-forbidden |
REST-VERSION-01 | MUST | versioning | The REST API MUST define a versioning strategy before production release, and the strategy MUST be supportable by the API gateway. | versioning-decided |
REST-SEC-01 | MUST | security | The REST API MUST require authentication for protected endpoints. | auth-protection |
REST-SEC-02 | MUST | security | The REST API MUST use token-based authentication or another approved modern authentication mechanism for protected endpoints. | token-auth |
REST-SEC-03 | MUST | security | The REST API MUST enforce object-level and function-level authorization on every protected operation. | 401-unauthorized, 403-forbidden |
REST-SEC-04 | MUST | security | The REST API MUST mitigate OWASP API risks including broken object level authorization, broken function level authorization, injection, and unrestricted resource consumption. | auth-protection, rate-limits-enforced, no-sensitive-data-in-urls |
REST-SEC-05 | MUST | security | The REST API MUST use HTTPS or another approved encrypted protocol for all traffic. | uses-https, encryption-in-transit |
REST-SEC-06 | MUST | security | The REST API MUST NOT expose sensitive information in URLs, query strings, logs, or unnecessary response fields. | no-sensitive-data-in-urls |
REST-SEC-07 | SHOULD | security | The REST API SHOULD use UUIDs or other non-sequential public identifiers where direct database identifiers would increase exposure risk. | pseudo-identifiers |
REST-SEC-08 | MUST | security | The REST API MUST implement CSRF protection where relevant to the authentication model and client interaction pattern. | csrf-protection |
REST-CAPACITY-01 | MUST | resilience-capacity | The REST API MUST define and enforce rate limits, throttling, or quotas according to capacity expectations. | rate-limits-enforced |
REST-CAPACITY-02 | MUST | resilience-capacity | The REST API MUST implement resilience controls such as timeouts, fallback behavior, and degradation handling according to business impact. | only-via-gateway, encryption-in-transit |
REST-OBS-01 | MUST | observability | The REST API MUST implement logs, metrics, and monitoring needed to observe validation failures, auth failures, traffic, latency, and dependency health. | rate-limits-enforced, message-integrity |
REST-PUBLISH-01 | MUST | publishing-governance | The REST API MUST be published through an API management platform. | published-via-api-management |
REST-PUBLISH-02 | MUST | publishing-governance | The REST API MUST be accessible only through approved API gateway paths and managed entry points. | only-via-gateway |
REST-PUBLISH-03 | SHOULD | publishing-governance | The REST API SHOULD be visible in a developer portal with documentation generated from the contract. | visible-in-dev-portal, docs-auto-generated |
REST-PUBLISH-04 | MUST | publishing-governance | The REST API MUST be published under an approved organizational domain. | official-domain |
REST-AUDIT-01 | MUST | contract-governance | The REST API MUST validate the specification, schema, and examples on every change. | spec-validated-on-change, schema-and-examples-pass |
REST-AUDIT-02 | MUST | contract-governance | The REST API MUST pass concept, design, security, and production-readiness checks before release. | concept-items-audited, design-items-audited |