API First

API First is part of the Stedin integration strategy. Integration guidelines for the integration strategy can be found here: Integratie richtlijnen v2.0.pptx

• define APIs first, before coding its implementation, using a standard specification language
• get early review feedback from peers and client developers

By defining APIs outside the code, we want to facilitate early review feedback and also a development discipline that focus service interface design on…

• profound understanding of the domain and required functionality
• generalized business entities / resources, i.e. avoidance of use case specific APIs
• clear separation of WHAT vs. HOW concerns, i.e. abstraction from implementation aspects
• APIs should be stable even if we replace complete service implementation including its underlying technology stack

Use events and callbacks for specific scenario’s

API Manager = Azure API Management

Message Broker = Azure ServiceBus (and Azure EventGrid)

Sector guidelines

The conventions closely follow the sector guidelines but may deviate. The Stedin conventions are leading. For reference, our guidelines may be annotated with:

• AO-n: “MFF BAS API Ontwerprichtlijnen v3.0 (vastgesteld)”, EDSN/NEDU, n-th item
• UR-n: “MFF BAS URI Richtlijnen v2.0”, EDSN/NEDU, n-th item

If an API will be made available within the sector, those APIs require review by the API review group. Contact your solution architect integration for this.

Additional notes

All integrations (including temporary APIs) need to conform to the conventions. Exceptions require agreement by the Design Authority Integration and if indicated as such the Architecture Board.