Skip to Content
MetamodelAPIsAPIs

APIs

What Is an API?

An API (Application Programming Interface) is a formal contract that defines how two systems communicate. It specifies what operations are available, what data must be provided, and what will be returned — without either side needing to know the internal workings of the other.

APIs are the connective tissue of modern architectures. Rather than systems sharing databases directly or being tightly coupled at the code level, APIs create well-defined boundaries that allow systems to evolve independently whilst continuing to interoperate.

Common API styles include:

  • REST — the most widely used style; uses HTTP verbs (GET, POST, PUT, DELETE) and typically exchanges JSON payloads
  • GraphQL — a query language for APIs that lets clients request exactly the data they need, avoiding over-fetching
  • gRPC — a high-performance, binary protocol suited to internal service-to-service communication
  • Webhooks — event-driven callbacks where a system pushes notifications to a registered URL when something occurs
  • Async / Message-based — APIs built on message queues or event streams (e.g. Kafka, AMQP), common in event-driven architectures

Why Document APIs in an Architecture Repository?

APIs are a critical dependency surface. When an API changes — even subtly — it can affect every consumer. Documenting APIs as first-class model items in ArchRepo provides:

  • Traceability — link APIs to the business processes, requirements, and outcomes they support
  • Dependency visibility — see at a glance which services, applications, and data sets an API connects to
  • Impact analysis — when considering a change, understand what is affected before making it
  • Non-functional coverage — associate availability, security, performance, and scalability mechanisms directly with the API
  • Governance — track approval state and transition steps for APIs moving from design to production

APIs in ArchRepo

In ArchRepo, APIs are model items identified by an auto-generated reference in the format API-1, API-2, etc.

Each API can be marked as internal (owned and operated within the solution) or external (a third-party or partner API consumed by the solution). This distinction is important for impact analysis — changes to external APIs are outside your control.

APIs support:

  • Status and transition states — track progress from design through to live and deprecated
  • Categories — group APIs (e.g. by domain, by consumer, by team) and view them in the APIs by Category view
  • Estimation — record effort estimates against APIs for planning purposes
  • Relationships to services, business processes, data sets, NFRs, and architectural quality mechanisms

Modelling API Data with Data Sets

The data exchanged via an API — request bodies, response payloads, event schemas, and error structures — can be modelled as entities within a Data Set. ArchRepo supports JSON entities specifically for this purpose, allowing you to document the fields, types, and constraints of API payloads in a structured way.

Doing so provides two significant benefits:

  1. Structured information exchange documentation — instead of a free-text description of what the API returns, you have a field-level schema that is queryable and referenceable by AI agents via the MCP integration.
  2. Data mapping — once your API payloads are modelled as Data Set entities, you can use ArchRepo’s data mapping feature to trace and map API data across other data sets in the solution (for example, mapping a REST response payload to the fields of a database entity or a downstream service’s input schema).

Link the Data Set to the API using the Generates or Receives relationship — or use Has Read Access / Has Write Access for APIs that read from or write to a shared data store.

OpenAPI Specification Editor

Every API in ArchRepo includes a built-in OpenAPI Specification Editor, accessible from the Specification tab (below the Narrative section). It allows architects to create and maintain formal OpenAPI 3.0.3 specifications for the API — directly alongside all other architecture documentation.

Key capabilities include:

  • Multiple versions — store and manage several specification versions per API, sorted by semantic version
  • Dual editing modes — edit raw YAML with syntax highlighting, or use the visual editor to add and modify endpoints, parameters, request bodies, responses, and schemas
  • Dataset entity integration — import schemas directly from Dataset entity definitions, with automatic drift detection when the source entity changes
  • OpenAPI validation — real-time conformance checking with errors and warnings
  • Export — download the specification as a .yaml file or copy it to the clipboard

Rather than defining the same data structure in your API spec and your database schema separately, you can import a Dataset entity directly into the OpenAPI specification as a component schema. ArchRepo tracks the link and alerts you if the entity definition changes — so your API contract stays aligned with the rest of your data model without manual checking. Because Dataset entities are also used in Data Mappings, this integration lets architects trace data transformations from API payloads through to databases and downstream services.

See OpenAPI Specification Editor for full details.

Fields Reference

See API Fields for a description of each field and guidance on what to record.

Last updated on
Business Acceptance Criteria FieldsAPI Fields