APIs

Introduction

APIs are a central mechanism for exposing and consuming functionality and data between applications.

To understand dependencies and data flows across the application landscape, APIs should be modelled explicitly and consistently.

This pattern describes a lightweight approach to API modelling in ADOIT using ArchiMate. It focuses on API ownership, consumption, and exchanged business information while deliberately avoiding technical implementation details and additional modelling constructs.

The approach represents a conscious trade-off between modelling detail and modelling effort. Rather than documenting every technical interaction and data flow explicitly, the pattern captures the information required for architecture-level transparency and analysis.

Design Principle

Make APIs Explicit and Ownership Clear

From an Enterprise Architecture perspective, API modelling should make it clear which Application Components are connected and what business-relevant data is exchanged between them.

Modelling APIs explicitly makes these dependencies visible and supports integration transparency, dependency analysis, and impact assessment.

To balance architectural insight with modelling effort, this pattern uses a small set of ArchiMate elements and relationships. The predominant direction of data flow is derived from the provider-consumer structure rather than modelled through additional relationships.

Modelling Structure

• APIs as Application Interfaces

  Each API is modelled as an Application Interface.

  The Application Interface:

  • represents the API through which an Application Component exposes functionality and data to other applications,
  • provides a stable architectural representation of the API,
  • remains independent of technical implementation details.

  APIs are not modelled implicitly through direct component-to-component connections.

• API Ownership via Application Components

  Each API should have one clearly identified providing Application Component.

  The providing Application Component composes the Application Interface.

  The provider is responsible for the lifecycle and evolution of the API from an organizational and management perspective.

  Application Component → composition → Application Interface

• API Consumption Made Explicit

  Applications consuming an API are explicitly connected to the Application Interface.

  The Application Interface serves the consuming Application Component.

  Consumers therefore connect to the API rather than directly to the providing Application Component.

  Application Interface → serving → Application Component

  This clearly distinguishes the provider from its consumers.

• Main Data Flow Convention

  To keep modelling lightweight, the predominant direction of data flow is derived from the provider-consumer structure:

  Providing Application Component → composition → Application Interface → serving → Consuming Application Component

  The Application Component that composes the API is considered the provider and the primary source of the relevant data. In this pattern, it is also considered responsible for the API from an organizational and management perspective, including its lifecycle and evolution.

  Application Components served by the API are considered consumers of the data.

  This convention deliberately simplifies the actual technical communication. APIs may involve requests, responses, and information flowing in both directions. These individual flows are not modelled separately.

  The pattern therefore represents the predominant business-relevant data flow rather than every technical interaction. This provides sufficient information for architecture-level dependency and impact analysis while keeping modelling and maintenance effort low.

• Exchanged Data via Business Objects

  The business-relevant information exchanged through an API is represented using Business Objects.

  Business Objects describe meaningful business information rather than technical payload schemas and can be reused across multiple APIs.

  Application Interface → access → Business Object

  Together with the provider-consumer convention, this identifies which business information is primarily provided through the API and which applications consume it.

• Runtime Support via System Software

  Where relevant, API runtime platforms such as API gateways or container platforms can be modelled as System Software.

  System Software serves the Application Interface.

  Runtime support does not imply API ownership.

  System Software → serving → Application Interface

  Runtime modelling is optional and should only be added where this information provides architectural value.

• Technical Details as Attributes

  Technical details such as:

  • protocol,
  • synchronous vs. asynchronous behaviour,
  • security mechanisms,
  • documentation links,

  are captured as attributes rather than additional model elements.

  Endpoints, methods, payload formats, and individual request/response messages are outside the scope of this pattern.

Resulting Modelling Pattern (Compact)

• Core Pattern

  Providing Application Component → composition → Application Interface (API) → serving → Consuming Application Component

  Application Interface → access → Business Object

  The core structure implies the predominant information flow: Provider → API → Consumer

• Optional Runtime Information

  System Software → serving → Application Interface

Do / Don't - AI System Modelling

• Do

  • Model every architecturally relevant API explicitly as an Application Interface
  • Assign a clear providing Application Component
  • Make API consumers explicit
  • Model business-relevant exchanged information using Business Objects
  • Use the provider → API → consumer structure to indicate the predominant data flow
  • Keep technical details as attributes
  • Add runtime information only where it provides architectural value

• Don't

  • Don’t connect Application Components directly when the API itself is architecturally relevant
  • Don’t model APIs implicitly
  • Don’t model every technical request and response
  • Don’t introduce additional elements solely to represent detailed data flows
  • Don’t mix runtime support with API ownership
  • Don’t model endpoints, methods, or payload schemas

Scope and Intent

• This pattern supports:

  • Integration transparency,
  • understanding API providers and consumers,
  • understanding predominant data flows,
  • dependency and impact analysis,
  • application portfolio planning.

• It is not intended to:

  • replace technical API documentation,
  • document every bidirectional data exchange,
  • describe detailed runtime or deployment architecture,
  • model endpoints, messages, or payload schemas.

Where more detailed analysis is required, additional ArchiMate concepts and relationships can be introduced. They should not be required for the standard lightweight API modelling approach.