APIn suunnitteluperiaatteet
Tiivis opas APIn käytettävyyteen, löydettävyyteen ja johdonmukaisuuteen, joka perustuu yhteisiin suunnittelusääntöihin ja todellisiin kuluttajien tarpeisiin.
Näin se toimii
Osio nimeltä “Näin se toimii”Vaiheet
Osio nimeltä “Vaiheet”- Kuluttaja ensin -suunnittelu: Aloita jokainen APIOps-sykli keräämällä käyttäjien tavoitteet ja toimialan ehdot, jotta APIt ratkaisevat todellisia ongelmia.
- Johdonmukainen nimeäminen ja käyttäytyminen: Sovelletaan yhteisiä käytäntöjä resursseja, virheitä ja formaatteja varten, jotta sovellusrajapinnat olisivat ennakoitavissa.
- Sopimusperusteinen: kaappaa rajapinta OpenAPIlla tai AsyncAPIlla ennen koodausta tiimien yhdenmukaistamiseksi ja automaation mahdollistamiseksi.
- Käytettävyys ja löydettävyys: Selkeä dokumentaatio ja esimerkit, jotta kehittäjät ymmärtävät nopeasti, miten APIta käytetään.
- Iteroi turvallisesti: Kehitä malleja pienissä, versioiduissa vaiheissa, jotta muutokset eivät häiritse nykyisiä kuluttajia.
Guidelines
Osio nimeltä “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 |