ADR 039: Dataset API Standard

Date: 2026-04-22
Status: accepted

Decision Makers: Architecture Board

Context

The CIVITAS/CORE platform is intended to serve as a reusable, open, and modular Smart City core platform. It is composed of multiple open-source components that together provide foundational capabilities such as identity management, API management, data integration, and platform interoperability.

As the platform continues to evolve, it is necessary to decide how data stored within the platform can be retrieved via an API in a reliable and consistent schema.

This ADR establishes a clear scope boundary for CIVITAS/CORE in order to:

• Avoid ambiguity for implementers and operators
• Ensure architectural consistency across deployments
• Enable community-driven extensions without bloating the core
• Provide a clear basis for documentation and future ADRs

Checked Architecture Principles

• [none] Model-centric data flow: this ADR does not influence this principle
• [full] Distributed architecture with unified user experience
• [none] Modular design: this ADR does not influence this principle
• [full] Integration capability through defined interfaces
• [none] Open source as the default: this ADR does not influence this principle
• [none] Cloud-native architecture: this ADR does not influence this principle
• [none] Prefer standard solutions over custom development: this ADR does not influence this principle
• [none] Self-contained deployment: this ADR does not influence this principle
• [none] Technological consistency to ensure maintainability: this ADR does not influence this principle
• [full] Multi-tenancy
• [none] Security by design: this ADR does not influence this principle

Decision

CIVITAS/CORE, as a data platform, bundles various technologies and standards and serves as a data hub, enabling domain-specific applications and other consumers to work with the data. These consumers must be able to rely on a stable API schema and understand which standard to expect.

The supported API standard will not be encoded in the URL schema, but instead defined as a mandatory, explicit attribute of the API configuration.

The URL schema remains standard-neutral:

/v1/datasets/{dataset_uuid}/{api_name}

Each API must explicitly declare its type via a controlled enum, for example:

• WFS
• WMS
• STA
• CUSTOM

If CUSTOM is selected, the user may define a free-form API name and behavior.

Additionally, the platform provides a machine-readable discovery mechanism that allows consumers to retrieve all available APIs for a dataset along with their associated standard.

Example:

GET /v1/datasets/{dataset_uuid}/apis

Response:

[
  {
    "name": "city-sensors",
    "url": "/api/v1/datasets/123/city-sensors",
    "standard": "STA",
    "version": "1.1"
  },
  {
    "name": "custom-export",
    "url": "/api/v1/datasets/123/custom-export",
    "standard": "CUSTOM"
  }
]

Consequences

Positive

• Clarity without implicit assumptions: Consumers can reliably identify the API standard via explicit metadata.
• Stable API contracts: The URL structure remains unchanged even if additional standards are introduced.
• Separation of concerns: The API path identifies the resource, while the standard is part of the API's semantic definition.
• Extensibility: New standards can be added without affecting existing endpoints or naming schemes.
• Compatibility with authorization mechanisms: Avoids complications with Rego-based routing and policy evaluation.

Negative

• Additional discovery step required: Consumers must query metadata or documentation to determine the API standard.
• Less self-descriptive URLs: The standard is not directly visible in the path.
• Slightly increased implementation complexity: Requires maintaining and exposing API metadata consistently.

Alternatives

• A1: Use the schema https://api.{{DOMAIN}}/v1/datasets/{{DATASET_UUID}}/{{API_NAME}} and let the user freely define {{API_NAME}}. A WFS API can be https://api.{{DOMAIN}}/v1/datasets/{{DATASET_UUID}}/wfs, but it can also be https://api.{{DOMAIN}}/v1/datasets/{{DATASET_UUID}}/wfs_gruenes_auto or https://api.{{DOMAIN}}/v1/datasets/{{DATASET_UUID}}/gruenes_auto.
• A2: Use the schema https://api.{{DOMAIN}}/v1/datasets/{{DATASET_UUID}}/{{API_NAME}} and reserve key names for standards so the user cannot use them. For example: WMS, WMTS, WFS, STA, etc. This can be enforced by an enum in the API Request Node, where the user can choose a standard or define an API name outside any standard via a free-text field using a CUSTOM option.
• A3: Encode the standard in the URL, for example https://api.{{DOMAIN}}/v1/datasets/{{DATASET_UUID}}/STA/{{API_NAME}}. This is immediately visible and human-readable and requires no additional discovery step, but it creates tight coupling between URL structure and semantics, may conflict with authorization mechanisms such as Rego, is harder to evolve without breaking API contracts, and increases the risk of naming conflicts and rigidity.