Skip to content
Technology transformation expertise firm · ARDIANE Group Innovate, secure, succeed

Glossary

API management: definition, components of a platform and related notions

Domain

Engineering

In brief

API management refers both to the discipline that governs the publication, security, monitoring and retirement of an organisation's programming interfaces, and to the family of tools that supports it. A breakdown in common use distinguishes a gateway, which receives calls, administration functions, a portal for developers and usage monitoring.

Page contents

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.

FAQ

Frequently asked questions

Another question? Ask us

What is API management?

API management refers to the discipline that governs the publication, security, monitoring and retirement of an organisation's programming interfaces. The term also refers to the family of tools that supports this discipline. A breakdown in common use distinguishes within these tools a gateway, administration functions, a portal for developers and usage monitoring.

What is the difference between API management and an API gateway?

The API gateway is the component that receives calls, controls access and routes requests to the services. API management covers a wider scope: the inventory of APIs, their documentation, their versions, their retirement and the measurement of their usage. The gateway is therefore one of the components of an API management platform.

What is a developer portal for?

A developer portal is the site where an organisation presents the catalogue of its APIs, their documentation and their access conditions. A developer discovers the available interfaces there, requests credentials and learns how to connect to them. The portal aims to spare the team that produces an API from briefing each consumer one by one.

What is the OpenAPI Specification?

The OpenAPI Specification, published by the OpenAPI Initiative on the openapis.org website, is an open standard for describing HTTP APIs, independent of the programming language. It is used to write the contract of an API in a YAML or JSON document. This document can then feed documentation, code generation and tests.

A project to bring to completion?

A first conversation is enough to understand your challenge, identify the right people and tell you frankly what we can bring.