API Contracts - Archyl Docs

Document and manage API specifications linked directly to your C4 architecture elements

API Contracts

API Contracts let you attach API specifications to your architecture elements, keeping documentation and design in sync. Archyl supports OpenAPI (REST), gRPC, GraphQL, and AsyncAPI contracts, with optional git synchronization.

Supported Contract Types

Type Format Use Case
HTTP (REST) OpenAPI 3.x (YAML/JSON) REST APIs, webhooks
gRPC Protocol Buffers (.proto) Service-to-service RPC
GraphQL GraphQL SDL (.graphql) Query APIs
Async AsyncAPI (YAML/JSON) Event-driven APIs, message queues

Creating a Contract

Manual Entry

  1. Navigate to your project
  2. Open the API Contracts tab
  3. Click New Contract
  4. Fill in the contract details:
    • Name — A descriptive name (e.g., "User Service API")
    • Type — HTTP, gRPC, GraphQL, or Async
    • Version — Semantic version (e.g., 1.0.0)
    • Endpoint — Base URL of the API
    • Description — What the API does
  5. Paste or write your specification content in the editor
  6. Click Create

Git Synchronization

Instead of maintaining contracts manually, you can sync them from a git repository:

  1. Click New Contract and select Git as the source type
  2. Choose a connected repository
  3. Specify the file path to the spec file (e.g., api/openapi.yaml)
  4. Set the branch to track (defaults to the repository's default branch)
  5. Archyl pulls the spec content and keeps it in sync

You can also use glob patterns to match multiple files. For example, api/**/*.yaml will match all YAML files under the api/ directory.

Sync Behavior

  • Specs are fetched from the repository when the contract is created
  • Use the Sync button to manually pull the latest version
  • The last sync timestamp is displayed on the contract card

Linking Contracts to Architecture

API contracts become meaningful when linked to the C4 elements they describe. A contract can be linked to systems, containers, components, or code elements.

Adding Links

  1. Open a contract's detail page
  2. Click Link to Element
  3. Select the C4 level (System, Container, Component, or Code)
  4. Choose the target element
  5. The link appears on both the contract and the element's detail panel

Viewing Linked Contracts

On the diagram, right-click any element to open its detail panel. Linked API contracts appear in the Contracts section with:

  • Contract name and version
  • Protocol type badge (HTTP, gRPC, GraphQL, Async)
  • Link to the full specification

Server Entries

Each contract can define multiple server entries — useful for documenting different environments or regions.

Field Description
URL The server base URL (e.g., https://api.example.com/v1)
Description Environment or purpose (e.g., "Production", "Staging")

The Specification Viewer

Archyl renders your API specifications with an interactive viewer:

  • OpenAPI — Endpoints grouped by tag, with request/response schemas, parameters, and examples
  • gRPC — Service definitions, RPC methods, and message types
  • GraphQL — Types, queries, mutations, and subscriptions
  • AsyncAPI — Channels, messages, and schemas

The viewer is read-only and always reflects the current content of the contract.

Event Channels

Event channels document the asynchronous messaging side of your architecture — Kafka topics, SQS queues, RabbitMQ exchanges, and similar.

Creating an Event Channel

  1. Navigate to your project
  2. Open the Event Channels tab
  3. Click New Channel
  4. Configure the channel:
Field Description
Name Channel name (e.g., "Order Created Events")
Direction produce or consume
Broker Type Kafka, NATS, SQS, RabbitMQ, Redis, Pulsar, or Custom
Topic Name The actual topic or queue name
Schema Format JSON Schema, Avro, Protobuf, or Text
Value Schema The event payload schema definition

Linking to Architecture

Event channels follow the same linking model as API contracts. Link a channel to the systems, containers, or components that produce or consume its events. This makes message flows visible directly on the architecture diagram.

Best Practices

Keep Specs Up to Date

  • Use git sync for specs that live in your codebase
  • Version your contracts following semantic versioning
  • Update the contract when the API changes

Link Everything

  • Every API-serving container should have at least one linked contract
  • Link event channels to both producers and consumers
  • Use links to make the diagram self-documenting

Organize by Service

  • One contract per service or bounded context
  • Use descriptive names that match your architecture naming
  • Include the API version in the contract version field

Document Servers

  • Add server entries for each environment
  • Include both internal and external endpoints
  • Keep URLs current as infrastructure changes

Next Steps