API Governance

Companies that want to implement APIs, to expose services internally or for external partners, must now organize themselves. We are talking about API governance. The basis.

?API governance : what is it??

?API governance is an approach intended to support an API strategy : easy, isn’t it ? In this case, it is based on a model specific to the company (centralized, decentralized or hybrid). Let's see it in more details

This approach brings together a set of technical and organizational projects such as : the definition of an API control center, the establishment of a multidisciplinary team (famous pizza team, from Jeff Bezos twenty years ago : to know if a team is large enough or too large : there must be enough slices for a pizza) with clearly defined roles and interactions, the definition of the processes linked to the API life, the implementation of change indicators and API traceability and security techniques.

?The implementation of governance often begins with a promising project that wants to deploy APIs and that will choose the API Manager for?the company.

?However, in this short article, we will not discuss the choice of API Manager, the implementation of governance?does?not depend on the chosen platform. We will “just” discuss here the establishment of governance. Here, we will just discuss the establishment of governance.

?The technical aspect of API governance

?The company's architects, brought together in a internal community of experts, will have to define the norms and standards of APIs, namely :

- The definition of interface standards used to create and publish APIs in the company

- The API security model used and the characteristics of their management

- The model of incoming and outgoing data structures

- The repository of existing APIs and that of their versions (Any unused API's will be discarded. We have to think Green for IT all the time?)

?Here are some of the?(not all) best practices for defining APIs :

?●?Use HTTP verbs

- GET, POST, DELETE, PUT, HEAD, OPTIONS

?●?Use standard response codes HTTP

- 200 OK

- 400 Bad Request

- 500 Internal Server Error

- 502 Bad Gateway

●?Display the major version of the API which should appear in the URL of the resources

GET /v1/orders

●?If possible, only support two versions of the same API at the same time. It allows developers to have time??to upgrade their applications with the new API

●?Try to preserve backward compatibility as much as possible, don’t forget to document it the API portal

?●?Define a single dictionary for the company's services, even in?multi-corporations

?Focus on Swagger and OpenAPI??

The easiest way to understand the difference is

·????????OpenAPI = Specification

·????????Swagger = Tools for implementing the specification

You? have?understood, OpenAPI is the official name of the specification. The development of the specification is fostered by the OpenAPI Initiative, which involves more than 30 organizations from different areas of the tech world — including Microsoft, Google, IBM, etc… . Smartbear Software, which is the company that leads the development of the Swagger tools, is also a member of the OpenAPI Initiative, helping lead the evolution of the specification.

Swagger?is the name associated with some of the most well-known, and widely used tools for implementing the OpenAPI specification. The Swagger toolset includes a mix of open source, free, and commercial tools, which can be used at different stages of the API lifecycle.

Why haven’t the Swagger tools changed their name to OpenAPI?

The Swagger team remains focused on building the most powerful, and the?easiest to use tooling for designing, documenting, developing, and testing APIs using the OpenAPI Specification, and will continue to grow and evolve our toolset to support the OpenAPI. These tools will continue to maintain the Swagger name.?Swagger.io

, the online home of the Swagger tooling and the open source Swagger projects, will also continue to be a go-to place to learn about the Swagger tools, and it?will also continue to contribute to the knowledge around the OpenAPI Specification, through training courses, tutorials, webinars and documentation for working with OpenAPI (as explained in https://swagger.io/blog )?

?Security

?For the choice of security rules, the security manager must study the criticality of the data to assess which protocol is the most suitable to respond to.

The OAuth2 standard will define three main players in secure exchanges between the customer who wishes to consume an API and the service provider.

?The principle is therefore as follows : the client must identify himself 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 give it to the service provider to prove their identity and request the outcome of the service call. Do you follow ?

?Once the technical aspect has been taken into account, the establishment of a team that will promote and support the APIs as well as the API Manager in the company takes place : with which team??Let's see in the next paragraph.

The (important) organizational aspect of API governance

?Sometimes, there is just?one team, sometimes, many but often in an unique program. But what is??sure,?is?this implementation of the API skills center is in the API Team.

The API Team is the guarantor of the evolution of the legacy of APIs and resources. It has both a strategic mission because it defines the trajectory of the evolution of the legacy and an operational mission because it defines the design rules of APIs, supports projects in the design of resources and deploys APIs on shelves (technical APIs or functional reusable by all company entities).

?The APIs competence center must therefore be made up of expert resources:

• On one hand, a sponsor with visibility at the level of the company's management committee, in order to highlight the API management platform and in order to attract new projects wishing to develop and deploy digital services. It’s essential !
• On the other hand, API manager experts, architects, technical experts to advise projects and design guides. Moreover, to lead this team, you need a pilot (Product Owner) who will supervise the delivery of guides, who will also be the main contact for projects requiring information and advice.
• Finally, you need to have a very good communicator (sometimes the same actor as the?Product owner), a kind of “scrum master” to connect the teams, to lead internal communities, to participate in external communities, to participate in webinars, to create training courses and so on

What are the core activities of the Team API?

● Legacy management

- Define the repositories and tools necessary for piloting

- Administer asset mapping

- Monitor the quality of APIs and resources

- Build internal and/or external portal (you can see my own article )

?● Functional design of APIs

- Support projects in the identification and design of APIs and resources

- Design strategic resources

?● The methodology

- Produce design guides (versioning, security, etc.) for manufacturers

- Produce user charters for consumer projects

?● Training and communication (you can read my own article)

- Build training materials for internal use (technical / business oriented)

- Build or lead?an internal community of developers to stimulate the creation of new services

- Participate in or lead an external community (such as API Thinking Collective, a French collective) to capitalize on, to share knowledge and skills around issues related to APIs

?To conclude this part, it is important that the API Team makes sure to optimize the use of the API management platform (API Manager) and to spread the API culture in the company. The objective that APIs become profitable by being reused by several projects or partners must be maintained.

We have seen?that, API governance is complex and does not work alone. It must be connected to change management, asset management, configuration management and governance of the existing service-oriented architecture (SOA) (with the objective of its eventual replacement) - in order to obtain an architecture API management that works for users, processes and systems in place in the business to….bring new outcomes for the company.

?