API Fields

Within ArchRepo you can document multiple APIs for your solution. Each API is identified by an auto-generated reference (API-1, API-2, etc.) and can be linked to the services, business processes, data sets, and non-functional requirements it relates to.

1. Description

• What it’s for: A concise summary of what this API does and who uses it.

• What to include:

  • Describe the primary purpose of the API in plain language.
  • Identify the main consumers — which applications, services, or external parties call this API.
  • Note any important constraints or context (e.g. “internal only”, “rate limited to 100 req/s”, “deprecated in favour of API-7”).

• Example: "Provides customer profile data to the web portal and mobile app. Returns name, contact details, and account status. Internal use only — not exposed publicly."

2. External

• What it’s for: Indicates whether this API is external to the solution — i.e. owned and operated by a third party or partner rather than your own team.
• What to include:
  • Set to Yes for APIs you consume but do not control: payment gateways, government data services, SaaS platform APIs, partner integrations.
  • Set to No for APIs owned and operated within your solution.
  • The external flag is significant for impact analysis: changes to external APIs are outside your control and may require your team to adapt reactively.

3. Protocols Supported

• What it’s for: Records the communication protocol(s) this API uses.

• What to include:

  • List the protocol(s) in use: REST, GraphQL, gRPC, SOAP, WebSocket, webhook, AMQP, Kafka, etc.
  • If the API supports multiple protocols, list all of them.
  • For message-based or event-driven APIs, note the broker or transport (e.g. “Kafka topic”, “RabbitMQ queue”).

• Example: "REST over HTTPS" or "gRPC (internal), REST (external-facing)"

4. Data Formats Supported

• What it’s for: Records the data format(s) the API accepts and returns.

• What to include:

  • List all supported formats: JSON, XML, CSV, Protobuf, Avro, plain text, binary, etc.
  • Note any format-specific constraints (e.g. “UTF-8 JSON only”, “XML with SOAP envelope”).

• Example: "JSON (primary), XML (legacy support)" or "Protobuf"

Tip: The request and response structures of the API can be modelled as entities within a Data Set — including JSON entities with field-level definitions. This provides structured documentation of what data the API exchanges and enables ArchRepo’s data mapping feature to trace payloads across other data sets in the solution. See APIs — overview for details.

5. API Versioning Strategy

• What it’s for: Describes how the API communicates its version to consumers.

• What to include:

  • Specify the versioning mechanism used:
    • URL path — e.g. /api/v2/customers (most common for REST)
    • URL query parameter — e.g. ?version=2
    • HTTP header — e.g. Accept: application/vnd.myapp.v2+json
    • Request body — version embedded within the payload (less common)
  • Note whether versioning is enforced or advisory.

• Example: "URL path versioning — current version is v2 (/api/v2/). The v1 path remains active but is deprecated."

6. Backward Compatibility Strategy

• What it’s for: Describes how the API handles changes without breaking existing consumers.

• What to include:

  • State whether previous versions remain available and for how long.
  • Describe the deprecation process: how consumers are notified, how long they have to migrate.
  • Note any breaking change policies (e.g. “breaking changes only in major versions”, “12-month deprecation window”).

• Example: "Previous major versions remain available for 12 months after a new version is released. Consumers are notified via the developer portal and via a Deprecation-Notice response header."