MUST start versioning from 1.0 [8]

In the API specifications we use a major and a minor version like 1.2. The major version should match the version in the filename. The first version always starts from 1.0. This version concerns the specification and is detached from the version of the implementation.
[Ref: UR-3.5.5, AO-02]

MUST mention client credentials scopes in description [84]

Mention the client credentials scope for each environment in the description of the API for convenience.

Client credentials scopes:
- DEV: api://86e7fee5-129f-44f5-8f57-0a0c07a7c539/.default
- TST: not implemented
- ACC: not implemented
- PRD: api://2fbafabc-39c3-4343-97a1-efdcbedb0c26/.default

Please don’t include a list of roles in the description. The roles and its descriptions can be found via the app registration. Including it in the OpenAPIspecification will lead to duplication of information which will likely become stale.

MUST add servers section in OpenAPI specification [85]

Use a dummy host name and the correct path in the openAPI specification

servers:
    - url: https://backend.stedin.net/v1/contractless-premises-cases

MUST identify the relevant components [86]

When designing an API you should always first try to identify the relevant components in the data dictionary. If the data dictionary does not contain the relevant components, you can add them by consulting the business object model (BOM) and logical data model (SLDM), or in dialog with a data architect or Saint team member.

Objects in the BOM can have underlying elements, such as specialized objects or attributes. You can navigate to them by clicking the Axon-link in the object viewer (right panel), and then opening the relationships tab. (In Axon you will also find definitions, on the summary tab.)

The BOM and its corresponding glossary in Axon are primarily about the meaning of data. The SLDM reflects the preferred structure of data, for example in a data warehouse. To ensure interoperability with the data warehouse, you must check for compatibility with the SLDM, meaning that it must in principle be possible to easily transform your data to an SLDM-based schema without loss of information.

The BOM and the SLDM are both in Dutch, although the business glossary in Axon does sometimes contain translations to English (in the field ‘Engelse naam’). If a term does not have an English translation, you are expected to find the best fitting term by consulting external standards such as the Common Information Model (CIM), a standard developed by the electric power industry that has been officially adopted by the International Electrotechnical Commission (IEC). You can find the CIM at sldm.stedin.net, under ‘Externe referentiemodellen’.

Both the data warehouse and the APIs are based on Stedin’s enterprise data models (such as the Stedin Logical Data Model, SLDM). However, each of these technologies require their own technology-specific data models. For example, the data warehouse requires relational models for implementation, while APIs require hierarchical models. Each of these technologies has its own unique implementation challenges and choices.

To ensure consistency across Stedin’s APIs, it is not desirable to expose the underlying data warehouse directly. Also, adding a transformation layer between the database of the data warehouse and its APIs, allows breaking changes to be managed. This way we can allow the data warehouse to evolve without causing breaking changes to API consumers.

You are invited to share any new insights, translations, corrections or additions to the BOM and SLDM with a data architect or Saint team member, so that we can continuously improve these models.

MUST include a link to a glossary item in Axon when extending the data dictionary with a new component [87]

If you extend the data dictionary with a new component (containing attributes), you are required to include a link to the glossary item in Axon that best captures its meaning, using this example format:

title: Connection
x-glossary: https://std-axon-p01.prd.stedingroep.nl:8443/glossary/view/id/1977

MUST add glossary and contact information in the specification extension [88]

In addition to the information in the openapi specification, an extension of the specification is used to add extra information like contact information and information about the business object (glossary). The specific business object corresponding to your API can be simply retrieved at https://std-axon-p01.prd.stedingroep.nl by browsing to the business object andy copying the url from the address bar, as shown in the example.

In the figure below a example of the ‘apispecificationextension.json’ is shown

{
    "glossary": {
        "name": "Elektriciteitsstation",
        "url": "https://std-axon-p01.prd.stedingroep.nl:8443/glossary/view/id/2160"
    },
    "contact": {
        "teamName": "BMR1",
        "email": "", //optional
        "url": "" //optional
    }
}