Skip to main content
Version: V2-Next

ADR 040: Separation of Data APIs and Management APIs via Subdomains in CIVITAS/CORE

Status​

Date: 2026-04-22
Accepted

Decision Makers: Architecture Board

Context​

CIVITAS/CORE acts as a data platform and central data hub, enabling users to manage datasets and expose them via APIs. These APIs are created and configured through the platform, for example via API Request Nodes, and can represent different standards such as WFS, WMS, SensorThings API (STA), or custom REST APIs.

Two fundamentally different types of APIs exist in the system:

  • Data APIs
    Provide access to dataset content for consumers such as applications, services, and external systems.
  • Management APIs
    Are used by the CIVITAS/CORE Portal frontend to interact with the platform backend for:
    • dataset management
    • API configuration, for example API Request Nodes
    • lifecycle operations
    • metadata and discovery

These APIs differ significantly in:

  • target audience (external consumers vs. portal/frontend)
  • security requirements (read access vs. administrative control)
  • lifecycle and stability (stable contracts vs. evolving platform features)
  • semantics (data access vs. control plane operations)

Additionally, API consumers must be able to reliably determine which standard, for example WFS, WMS, STA, or CUSTOM, an API implements, without relying on implicit assumptions such as URL structure or documentation.

At the same time, API contracts must remain stable, as changes to schemas or URL structures can break integrations and lead to a loss of trust.

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​

Separation of Data Plane and Control Plane via Subdomains​

  • Data APIs (Data Plane)
https://api.<domain>/v1/datasets/{dataset_uuid}/{api_name}
  • Management APIs (Control Plane)
https://portal-backend.<domain>/v1/...

This separation reflects different responsibilities, consumers, and security models.

Consequences​

Positive​

  • Clear separation of concerns
    Data access and platform management are strictly separated (data plane vs. control plane).
  • Explicit and reliable API semantics
    No implicit assumptions based on URL or payload are required.
  • Stable API contracts
    URL structure remains stable even when new standards are introduced.
  • Improved security model
    Different authentication and authorization strategies per subdomain.
  • Alignment with CIVITAS/CORE architecture
    Dataset APIs map cleanly to the data plane.
  • Operational flexibility
    Independent routing, scaling, monitoring, and rate limiting.

Negative​

  • Increased operational complexity
    Multiple subdomains, TLS certificates, and gateway configurations.
  • Cross-origin considerations
    Portal frontend to Management API communication may require CORS handling.
  • Higher documentation effort
    Separation of domains and responsibilities must be clearly communicated.

Alternatives Considered​

1. Path-based separation​

Example:

  • Management API
    https://<domain>/api/v1/...
  • Data API
    https://<domain>/data/v1/...

Pros:

  • Simpler infrastructure
  • No cross-origin issues

Cons:

  • Weaker separation of concerns
  • Harder to enforce security and policy boundaries
  • Less explicit architectural model
  • High impact in codebase

Rationale​

This approach ensures a simple, explicit, and stable model for API consumption:

  • The URL remains stable and technology-agnostic
  • The API standard is explicitly defined and machine-readable
  • Consumers can reliably discover and use APIs without ambiguity

The separation into subdomains reinforces the distinction between:

  • data plane (data consumption)
  • control plane (configuration and management)

This aligns with modern platform architecture patterns and supports scalability, security, and maintainability of CIVITAS/CORE.

Notes​

  • The naming convention (portal-backend. and api.) must be consistent across environments
  • The Management API is intended for portal interaction and not as a public integration interface