Establish and Document the Application's Published and Consumed APIs - Application Management Best Practices

Establish and Document the Application's Published and Consumed APIs

(Chapter 65 of Application Management Best Practices)

Executive Summary: Chapter Overview

IF4IT

The Bottom Line

Other teams cannot integrate correctly, and the Application team cannot change interfaces safely, without knowing what an Application exposes and what it relies on. This chapter documents every Published API with its purpose, operations, consumers, versioning, security, service levels, and deprecation approach, ideally generated from definitions in the Code Repositories, and every Consumed API with its provider, the operations relied upon, and the effect of its failure or change. Consumers are notified of Published API changes in advance.

Core Concepts

Concept	Definition & Strategic Role
Application Programming Interface (API)	A defined, documented interface through which an Application exposes specific functions, services, or data for use by other Applications or Systems, or through which it uses those of another. An API is an interface, distinct from the Integrations that may use it.
Published API	An API the Application exposes to others, documented with its specification, operations and data, known consumers, version and versioning policy, security and access requirements, service levels, and deprecation approach. Knowing its consumers lets the team change it without unexpectedly breaking anyone.
Consumed API	An API the Application uses from another Application or System, documented with its provider, the operations relied upon, the impact if it becomes unavailable or changes, and whom to contact. It reveals in advance exactly where the Application will be affected.

Quick Q&A

Question: Where should Published API specifications come from, and where should they be recorded?

Answer: They should preferably be generated from the API definitions held in the Application’s Code Repositories and then linked or published into the Digital Library, together with each API’s known consumers. Both Published and Consumed APIs are reviewed with every Release, and consumers are notified of Published API changes in advance.

Question: What must be established for each API the Application consumes from a provider?

Answer: Establish which Application or System provides it, which of its operations the Application relies on, what happens if it is unavailable or changes, and whom to contact about it. Recording this reliance reveals, before a provider changes or fails, exactly where the Application will be affected.

This chapter explains how to establish and document the Application Programming Interfaces (APIs) an Application exposes to others and the APIs it uses.

Definitions

An Application Programming Interface (API) is a defined, documented interface through which an Application exposes specific functions, services, or data for use by other Applications or Systems (a Published API), or through which it uses those of another (a Consumed API).

Establish the Application’s APIs

Published APIs. For each API the Application exposes, establish its purpose, its operations and data, its consumers, its version and versioning policy, its security and access requirements, its service levels, and its deprecation approach.
Consumed APIs. For each API the Application uses, establish which Application or System provides it, which operations the Application relies on, what happens if it is unavailable or changes, and whom to contact about it.

Record Published APIs with their specifications, preferably generated from the API definitions in the Application’s Code Repositories and linked or published into the Digital Library, and record each one’s known consumers. Record Consumed APIs with their providers and the Application’s reliance on them. Review both with every Release, and notify consumers of Published API changes in advance.

Establish and Document the Application's Published and Consumed APIs — Application API provider and consumer relationships… — Figure: Application API provider and consumer relationships, illustrating the distinction between Published APIs and Consumed APIs, their interface boundaries, request and response flows, API contracts, security requirements, ownership, versioning, and dependency management.

Best Practice: Establish and Document the Application’s Published and Consumed APIs

It is a best practice to both establish and document the solution for an Application’s interfaces: record every API it publishes, with its specification, consumers, versioning, and security, and every API it consumes, with its provider and the Application’s reliance on it.

Benefits: Documented Published APIs let other teams integrate correctly without repeated consultation, and knowing their consumers lets the Application team change them without breaking anyone unexpectedly. Documented Consumed APIs reveal, before a provider changes or fails, exactly where the Application will be affected.

The Integrations Inventory and Attributes describes how connections between Systems, including those made through APIs, are recorded.

How to cite this page

When referencing this page in academic work, internal standards, or external publications, include the page title, IF4IT as author and publisher (The International Foundation for Information Technology (IF4IT), LLC), the URL, and your access date.

Example (informal web citation):

The International Foundation for Information Technology (IF4IT), LLC. Establish and Document the Application's Published and Consumed APIs | Application Management Best Practices. https://if4it.org/best-practices/application-management-best-practices/establish-and-document-the-application-s-published-and-consumed-apis/ (accessed 2026-10-30).

See About Us for content governance and site-wide citation guidance.

Legal Disclaimers

Definitions

Establish the Application’s APIs

Document and Share the APIs

Best Practice: Establish and Document the Application’s Published and Consumed APIs

Connections to Related IF4IT Practices and Inventories

How to cite this page