Companies that want to implement APIs, to expose services internally or for external partners, need to get organized today. We call it “API Governance”.
API governance has two aspects, the first is technical because it is necessary to define standards and norms for the company’s APIs and the second is organizational because it is necessary to manage and develop the use and implementation of APIs.
The implementation of governance often starts with a promising project that aims to deploy APIs and for which we will choose the company’s API manager.
However, in this article we will not address the choice of the API Manager, as the implementation of governance will not depend on the chosen platform. We will discuss here the implementation of the governance.
The technical aspect of API governance
The company’s IS architects, working together in a community of experts, will have to define the norms and standards for APIs, including:
● The definition of the interface standards used to create and publish APIs in the enterprise.
● The security model of the APIs employed and the characteristics of their management.
● The model for incoming and outgoing data structures.
● The repository of existing APIs and their versions.
Some best practices for defining APIs include:
● Using HTTP verbs
– GET, POST, DELETE, PUT
● Use standard HTTP response codes
– 200 OK
– 400 Bad Request
– 500 Internal Server Error
● Show the major version of the API that should appear in the URL of the resources
GET /v1/orders
● Support only two versions of the same API (n, n-1) at a time if possible.
● Try to preserve backward compatibility as much as possible
● Define a single dictionary for the enterprise services
There are tools such as Stoplight or SwaggerHub to help project teams to properly design the interfaces of APIs.
For the choice of security rules, the CISO must study the criticality of the data to evaluate which protocol is the most suitable to respond.
The OAuth2 standard will define three main actors in the secure exchanges between the client that wants to use an API and the service provider.
It works as follows: the client must identify itself to the authorization server, either with a key or with a username and password. The authorization server will provide a token to the client who can then expose it to the service provider to prove his identity and request the result of the service call.
Once the technical aspect is taken into account, the team that will promote and support the APIs and the API Manager in the company must be set up.
The organizational aspect of API governance
This implementation of the API competence center is referred to as the API Team.
The API Team is responsible for the evolution of the APIs and resources. It has both a strategic mission because it defines the evolution path of the assets and an operational mission because it defines the API design rules, supports projects in the design of resources and deploys off-the-shelf APIs (technical or functional APIs that can be reused by all the company’s entities).
The API competence center must therefore be made up of experts:
On the one hand, a sponsor with visibility at the level of the company’s management committeein order to highlight the API management platform and to attract new projects eager to develop and deploy enterprise services.
On the other hand, API manager experts, architects, technical experts (Java, DevOps) to advise on projects and design guides. Finally, to lead this team, you need a pilot (Product Owner) who will supervise the delivery of the guides and communication and who will also be the main contact for projects requiring information and advice.
What are the key activities of the API Team?
● Asset management
– Define the repositories and tools necessary for management
– Manage the mapping of assets
– Monitor the quality of the APIs and resources.
● The functional design of APIs
– Support projects in the identification and design of APIs and resources
– Design strategic off-the-shelf resources
● Methodology
Produce design guides (versioning, security…) for manufacturers
– Produce user charters for consumer projects
● Training and communication
– Build training materials for internal use
– Build and animate a community of external developers to stimulate the creation of new services
Finally, it is important that the API Team ensures that the use of the API management platform (API Manager) is optimized and that the API culture is spread throughout the company. The objective that APIs become profitable by being reused by several projects or partners must be maintained.
The following diagram shows the interactions between the API Team and the different teams in the company.
API governance does not work in an isolated way. It must be connected to change management, asset management, configuration management, and the existing SOA governance (with the goal of replacing it) – to achieve a complete API management architecture that works for the users, processes, and systems in place in the enterprise.
