Definition of API management
An API (application programming interface) is the contract through which a piece of software makes its functions or data available to other software. API management refers in common usage to two related things: a discipline, which governs the life of an organisation’s APIs from their design to their retirement, and a family of tools, which handles their exposure, protection and monitoring.
The public documentation of three cloud providers gives examples. Microsoft presents Azure API Management as an API management platform covering their lifecycle, Google describes Apigee as its API management platform, and AWS describes Amazon API Gateway as a service for creating, publishing, maintaining, monitoring and securing APIs. Software from specialised vendors adds to these.
What API management settles when APIs multiply
When an organisation’s APIs multiply, questions remain open if nobody owns them: which APIs exist, who consumes them, with what rights, in which version. The discipline answers them by four means:
- an inventory of APIs, with an owner for each;
- security rules applied at one point, instead of being rewritten in each application;
- published documentation, which allows a consumer to connect without calling on the producing team;
- a versioning and retirement policy, announced to consumers.
It is also used to open up a legacy system without modifying it, an encapsulation strategy described on our page on application modernisation.
The components of an API management platform
The Azure API Management documentation distinguishes a gateway, a management plane and a developer portal; the Apigee documentation describes a layer of proxies placed in front of the services and a portal for developers. Under names that vary from one product to another, a breakdown in common use retains four functions.
| Component | Role |
|---|---|
| API gateway | Receives calls, checks credentials, applies quotas, routes to the relevant service |
| Administration | Used to declare APIs, their access rules and their versions |
| Developer portal | Presents the catalogue and documentation, receives access requests |
| Monitoring | Logs calls, measures usage, raises alerts in the event of an anomaly |
Two public specifications recur in this field: OpenAPI, published by the OpenAPI Initiative, for writing the contract of an HTTP API, and the IETF OAuth 2.0 authorisation framework (RFC 6749), through which a third-party application obtains limited access to an HTTP service.
API management, API gateway, IT urbanisation, IT master plan: not to be confused
The gateway is the runtime component of API management. Installed without an inventory, without owners and without a versioning policy, it routes calls without governing them.
IT urbanisation sets the breakdown of the information system and the rules of exchange between its parts. API management comes in downstream: it applies these rules to the interfaces actually exposed.
Enterprise architecture describes the entire organisation, from the business to the infrastructure. APIs are one mode of exchange among others, alongside events and files.
The IT master plan is a planning document. It can include the deployment of an API platform among its workstreams and allocate it a budget, without describing how it works.
A textbook case: bus timetables opened up to third-party applications
Take a public transport network that wants to let third-party applications display the next departures of its buses. The team describes the API in an OpenAPI document and publishes it on the developer portal. An application vendor registers there and receives credentials. On each call, the gateway checks these credentials, applies the agreed quota and passes the request on to the passenger information system.
Later, the response format has to change. A version 2 is published, and the retirement of version 1 is announced with a date. Call monitoring shows which consumers are still using the old version, so they can be warned before the cut-off.
The choice of exchange mode and the design rules for interfaces are covered on our page dedicated to IT architecture.