Decisions and steps we have taken that have proven to be effective in implementation of an API Management program:
1. Define security models upfront
Security policies should not be invented on the fly by each API designer. In our case we identified a limited set of security policies which we wanted to support, and the API designer selected from that list. This has resulted in a consistent and reliable security implementation.
2. Automate publication to the Dev Portal
The design platform, as the system of record for API data, is the logical point from which information can be published to the Developer Portal. We elected to do this once the API reached a specific lifecycle state. This allowed us to automate the creation of entries in the Developer Portal with API descriptions expressed in Markdown, and with request and response examples presented in the portal along with the OpenAPI specification. By mapping the API in the design platform to various taxonomies we were able to control the layout out of the API in the portal.
3. Adopt standards for completeness
Our initial experience with the design platform led us to realize that the API designer was unlikely to fully define the API, especially to the degree necessary to support automation of policies and API portal integration. We successfully introduced a self-enforced governance checklist which let the API designer validate their work, and which resulted in higher quality products.
4. Business traceability
Once several hundred APIs have been created it becomes difficult to understand what has been created. To address that we represented a business capability model within the design platform and mapped each API to a part of capability hierarchy. This gives us the ability to look at a part of the business and see which APIs are supporting that function. We similarly implemented a Journey taxonomy, for the same purpose.
