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:
- 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.
- 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.
Fields Reference
See API Fields for a description of each field and guidance on what to record.