MUST follow API first principle [1]
You must follow the API First Principle, more specifically:
- MUST define APIs first, before coding its implementation, using OpenAPI as specification language
- MUST design your APIs consistently with these conventions
- MUST call for early review feedback from peers, client developers and the Design Authority Integration
MUST provide API specification using OpenAPI 3.x [2]
For every API an OpenAPI 3.x specification should be published on the developer portal.
[Ref: AO-23]
MUST use UK English [3]
APIs within Stedin must be written in (UK) English. This includes URLs, headers, parameters, objects, arrays, properties and all documentation.
[Ref: AO-1]
The values as part of the resource data should be in Dutch. This also includes the values of enums.
MUST separate English words with appropriate separator character [4]
As general remark always use the applicable separator between English words.
| Title Case | camelCase | kebab-case | PascalCase |
|---|---|---|---|
| Use in API title and descriptions | Use in field names | Use in paths | Use in Postman variables |
| Work Order | workOrder | work-order | WorkOrder |
| Net Function | netFunction | net-function | NetFunction |
Use hyphen in API path for readability when the parts of the path are not hierarchical. If the parts of the path are hierarchical then use slashes.
[Ref: UR-04, AO-16] See also payload and URL conventions.
MUST reference environments 1-on-1 between APIM and backend [5]
API management is available on 4 environments: DEV, TST, ACC, and PRD. For each API one environment is only allowed to connect to one (corresponding) backend environment. It’s not allowed to connect APIM DEV to the backend DEV and TST environments.
SHOULD implement a 501 mock policy when backend environment is not setup [6]
If a backend environment is not available is should implement a mock policy that returns an 501 “Not Implemented” response.
SHOULD prefer APIs and events in data replication scenarios [7]
For data replication between two systems the use of APIs and events are preferred. This will allow the same APIs to participate in replication scenarios as well as on-demand requests. Which reduces the complexity and development burden on the provider team and system. “CUD” (Created,Updated,Deleted) or “mutated” events can be used to communicate state changes while an API can be used for a full load and consistency checks. The API should offer a “modifiedAfter” parameter to allow consumers to efficiently get the latest changes.
If replication is not feasible via APIs and events, alternative approaches can be discussed in the integration design authority.
MUST have a Stedin-team as owner of external parties [83]
APIs provided by external parties are called “Thirdparty” APIs. A team within Stedin will always be responsible for deploying and maintaining these APIs on Azure API Management. That team will also be the owner of the App Registration. Examples of this are the Ceres and Blicker APIs.
APIs provided by Stedin but consumed by external parties are classified “Public”. The App Registrations for these external consumers are maintained by Saint. Saint will request the roles on behalf of the external party and provide them with credentials. Assigning the ownership to Saint is chosen as external consumers might, just as internal consumers, need access to more than one API. Therefore one team cannot be assigned for the ownership of the app registration for the external party. Besides, assigning ownership to Saint prevents the one specific team from accessing other API’s which they possibly could generate secrets for.