Skip to content

ADR-0007: Define API Gateway and External API Architecture

  • Status: Accepted
  • Date: 2026-10-09
  • Decision Owners: Zelvoryqa Architecture
  • Technical Area: API Architecture / Service Communication / Security
  • Related ADRs:
  • ADR-0001: Adopt Microservices Based on Business Capabilities
  • ADR-0002: Adopt Multi-Tenant SaaS Architecture
  • ADR-0003: Define Service Data Ownership and Tenant Data Isolation
  • ADR-0004: Adopt Event-Driven Integration
  • ADR-0005: Define Synchronous Service Communication
  • ADR-0006: Define Authentication, Organization Membership, and Authorization

Context

Zelvoryqa is a multi-tenant SaaS platform composed of independently deployable services aligned with business capabilities.

External clients, including the Zelvoryqa web application and future authorized integrations, require a consistent and secure mechanism for accessing platform capabilities.

ADR-0001 establishes service boundaries and business capability ownership.

ADR-0002 establishes organizations as logical tenant boundaries.

ADR-0003 establishes authoritative service data ownership and organization-scoped data isolation.

ADR-0004 establishes event-driven integration for asynchronous communication.

ADR-0005 establishes requirements for synchronous service communication.

ADR-0006 establishes authentication, organization membership, organization scope, authorization, and tenant isolation requirements.

Without a defined external API architecture, clients may need to communicate directly with multiple internal services, manage inconsistent authentication mechanisms, understand internal deployment topology, and handle service-specific networking and error behavior.

Direct external access to internal services would also increase the number of exposed security boundaries and complicate centralized traffic management.

Zelvoryqa requires an external API architecture that provides a consistent client-facing interface while preserving independent service ownership and distributed security enforcement.

The architecture must address:

  • External API entry points
  • API Gateway responsibilities
  • Client authentication and organization context
  • Authorization enforcement boundaries
  • Routing to business services
  • Public API contracts
  • API versioning and compatibility
  • Request validation
  • Error handling
  • Timeouts and cancellation
  • Rate limiting and abuse protection
  • External API composition
  • Observability and auditability
  • Internal service exposure
  • Availability and failure handling

Decision

Zelvoryqa will adopt a centralized API Gateway as the primary entry point for external API requests.

External clients will interact with platform capabilities through explicitly defined, versioned APIs.

The API Gateway will provide common edge responsibilities, including request routing, authentication integration, trusted context establishment, traffic controls, and observability.

Business services will retain ownership of their business capabilities, operational data, authorization requirements, and business validation rules.

The gateway must not become the authoritative owner of business state or a centralized implementation of business logic.

Internal synchronous service communication and asynchronous event-driven integration will remain governed by ADR-0005 and ADR-0004, respectively.

The architecture will follow the principles below.

External Clients Must Use Controlled API Entry Points

External clients must access protected Zelvoryqa business capabilities through explicitly approved external API entry points.

The API Gateway will serve as the primary entry point for ordinary client-facing API traffic.

Conceptually:

                  External Clients
                         |
              +----------+----------+
              |                     |
         Web Application      External Integrations
              |                     |
              +----------+----------+
                         |
                         v
                    API Gateway
                         |
          +--------------+--------------+
          |              |              |
          v              v              v
     Order Service  Inventory Service  Warehouse Service

Internal business services must not be directly exposed to untrusted external clients by default.

Any future externally accessible endpoint that bypasses the primary gateway must be explicitly justified and must enforce equivalent security, traffic management, and observability requirements.

The gateway must not expose internal service topology, credentials, or implementation details unnecessarily.

The API Gateway Must Remain Infrastructure-Oriented

The API Gateway will manage cross-cutting concerns associated with external API access.

Its responsibilities may include:

  • Request routing
  • Authentication integration
  • Establishing trusted identity and organization context
  • Request size and protocol limits
  • Rate limiting and abuse protection
  • Traffic management
  • Request correlation
  • Distributed tracing integration
  • Common error response handling
  • API version routing
  • Access logging
  • Approved protocol translation

The gateway must not become responsible for:

  • Owning business entities
  • Executing authoritative business transactions
  • Directly accessing service-owned databases
  • Implementing inventory reservation rules
  • Managing order lifecycle transitions
  • Coordinating distributed business transactions
  • Replacing service-level authorization
  • Maintaining authoritative business state

For example, the gateway may route an inventory reservation request to Inventory Service, but Inventory Service remains responsible for validating availability, enforcing authorization, and applying the reservation.

This separation preserves the business capability boundaries established by ADR-0001 and the data ownership requirements established by ADR-0003.

External APIs Must Use Explicit Contracts

External API endpoints must be defined through explicit, documented contracts.

Contracts must establish the expected request and response behavior for each operation.

As applicable, contracts should define:

  • Resource identifiers
  • Request parameters
  • Request and response schemas
  • Required authentication
  • Organization context requirements
  • Authorization expectations
  • Validation constraints
  • Error responses
  • Pagination
  • Filtering and sorting
  • Idempotency requirements
  • Compatibility expectations
  • Relevant consistency guarantees

External clients must not be required to understand internal service deployment topology or internal communication protocols.

An external API contract may remain stable even when internal services are reorganized or their implementation technologies change.

The specific API description format and contract tooling will be selected separately.

External APIs Will Use HTTP-Based Resource Interfaces

Zelvoryqa will use HTTP-based APIs with resource-oriented interfaces as the default approach for external client communication.

External API operations should use appropriate HTTP methods and semantics.

For example:

GET    /api/v1/inventory/items
GET    /api/v1/inventory/items/{itemId}
POST   /api/v1/inventory/reservations

GET    /api/v1/orders
GET    /api/v1/orders/{orderId}
POST   /api/v1/orders

These paths are illustrative and do not establish the final endpoint catalog.

Resource ownership and API design should reflect business capabilities rather than internal infrastructure components.

State-changing operations must use explicit contracts that define their effects, validation requirements, and retry behavior.

An HTTP method's expected behavior does not guarantee that an operation is safe to retry. The underlying implementation must prevent unintended duplicate business effects when the same logical operation is repeated.

The initial external API version will use a versioned namespace such as /api/v1.

The final conventions for endpoint naming, API schemas, and documentation will be defined separately.

Authentication Must Be Integrated at the Gateway

The API Gateway must authenticate protected external requests using trusted authentication mechanisms.

The gateway must reject requests with missing, invalid, or expired credentials before routing them to internal services.

Authentication must establish the requesting principal's identity.

Successful authentication does not automatically establish organization membership, permission to perform an operation, or access to a requested resource.

The gateway must not treat client-provided identity information as trusted without appropriate verification.

Authentication behavior must remain consistent with ADR-0006.

The specific identity provider, authentication protocol, credential format, and validation mechanisms will be defined separately.

Organization Context Must Be Established and Preserved

Organization-scoped external API requests must have an explicitly established organization context.

The gateway may obtain requested organization context from an approved request mechanism, such as a route parameter, request header, or authenticated session context.

However, a client-provided organization identifier must not be treated as proof of authorization.

Organization context must be validated against trusted identity and authorization information before being relied upon.

Conceptually:

External Client
      |
      | Authenticated Request
      | Requested Organization A
      v
API Gateway
      |
      | Establish Trusted Identity Context
      | Validate or Resolve Organization Context
      v
Inventory Service
      |
      | Enforce Authorization
      | Enforce Resource Ownership
      v
Organization A Inventory

The gateway must preserve the necessary trusted identity and organization information when forwarding requests.

Receiving services must independently enforce their applicable authorization and tenant-isolation requirements.

Missing, invalid, ambiguous, or unauthorized organization context must not result in unrestricted access.

The exact organization context representation and propagation mechanism will be defined separately.

Authorization Must Remain Enforced by Business Services

The API Gateway may perform authorization checks that can be evaluated at the edge.

These checks may include determining whether a principal is permitted to access an API capability or requested organization.

However, gateway authorization must not replace authorization within business services.

Business services remain responsible for:

  • Enforcing capability-specific permissions
  • Validating applicable organization scope
  • Verifying resource ownership
  • Enforcing business authorization policies
  • Protecting organization-owned operational data

For example, the gateway may determine that a user is authenticated and has access to Organization A.

Inventory Service must still determine whether the user is authorized to adjust inventory and whether the target inventory item belongs to Organization A.

Internal service calls, background jobs, and event consumers must not bypass these requirements.

This preserves the authorization boundaries established by ADR-0006.

Request Validation Must Occur at Appropriate Boundaries

The API Gateway must enforce applicable external API constraints and reject requests that violate those constraints before routing them to internal services.

Examples include:

  • Unsupported HTTP methods
  • Invalid request framing
  • Excessive request sizes
  • Unsupported content types
  • Invalid authentication credentials
  • Invalid routing parameters

Business services remain responsible for validating requests according to their own contracts and business rules.

For example, Inventory Service must validate whether a requested inventory adjustment is permitted and whether the quantity satisfies applicable business constraints.

Gateway validation must not be treated as a replacement for receiving-service validation.

API Versioning and Compatibility Must Be Explicit

External APIs must support controlled evolution without unnecessarily breaking existing clients.

Breaking contract changes must be introduced through an explicitly defined compatibility or versioning strategy.

The platform must distinguish between:

  • Backward-compatible changes
  • Breaking changes
  • Deprecated operations
  • Removed operations
  • Changes to documented behavior

Clients must not be required to adopt internal service changes immediately when those changes can be accommodated without altering the external contract.

The API Gateway must support routing requests according to the requested API version when version-specific routing is required.

However, API versioning must not require the gateway to duplicate authoritative business logic.

The specific versioning rules, deprecation periods, and compatibility policies will be defined separately.

Error Handling Must Be Consistent

External API contracts must provide consistent and predictable error behavior.

Error responses should allow clients to distinguish between relevant failure categories, including:

  • Authentication failures
  • Authorization failures
  • Invalid requests
  • Resource-not-found conditions
  • Business validation failures
  • Conflicts
  • Rate limiting
  • Temporary service unavailability
  • Internal processing failures

Error responses must provide sufficient information for appropriate client handling without exposing internal service topology, credentials, sensitive implementation details, or unauthorized organization data.

The API Gateway must translate infrastructure-level errors into consistent, documented external error responses when those errors would otherwise expose internal implementation details or violate the external API contract.

Business services remain responsible for defining the meaning of business-specific failures.

A timeout or interrupted connection does not necessarily mean that a state-changing operation failed. The receiving service may have successfully completed the operation even though the client did not receive a response.

Clients must not assume that a communication failure means the requested operation was not executed.

Where applicable, external contracts must provide safe retry, idempotency, or operation-status mechanisms consistent with ADR-0005.

The exact error response envelope and HTTP status mapping will be defined separately.

Timeouts and Cancellation Must Be Bounded

External API requests must have bounded execution times appropriate to the requested operation.

The gateway must enforce appropriate request timeouts and resource limits.

When forwarding synchronous requests, downstream operations must respect the remaining request deadline.

A downstream service must not extend an existing overall request deadline.

Cancellation should propagate through synchronous dependencies where supported to avoid unnecessary work.

Timeout and cancellation behavior must remain consistent with ADR-0005.

Long-running business operations must not require an external HTTP connection to remain open for the duration of processing.

Long-running operations that cannot reliably complete within a synchronous request deadline should use an asynchronous operation contract, allowing clients to initiate the operation and retrieve its status without maintaining an open connection.

The exact timeout values and long-running operation patterns will be defined separately.

Rate Limiting and Abuse Protection Must Be Supported

The external API architecture must support traffic controls that protect platform availability and prevent abusive or excessive request patterns.

Controls may include:

  • Request rate limiting
  • Request size limits
  • Connection limits
  • Concurrency limits
  • Burst controls
  • Resource-specific quotas
  • Organization-aware usage limits

Traffic controls may be applied at different scopes, including:

  • Client identity
  • Authenticated principal
  • Organization
  • API operation
  • Integration identity
  • Platform-wide capacity

Rate limiting must not be treated as a substitute for authentication, authorization, or tenant isolation.

Shared infrastructure must enforce appropriate resource and traffic limits to prevent excessive usage by one organization from degrading service availability or performance for other organizations.

The specific rate-limiting algorithms, quota policies, and enforcement technologies will be defined separately.

External API Composition Must Preserve Service Ownership

Some client-facing operations may require information from multiple business services.

The architecture may support explicitly defined API composition when it improves client usability or reduces unnecessary client-side coordination.

However, API composition must not move authoritative business ownership into the gateway.

Conceptually:

External Client
       |
       v
API Gateway
       |
       v
Application Composition Capability
       |
       +---- Order Service
       |
       +---- Inventory Service
       |
       +---- Shipping Service

A composition capability may combine responses from multiple services for an approved client-facing use case.

It must not directly access service-owned databases or bypass service authorization requirements.

Composition must preserve:

  • Service ownership
  • Organization scope
  • Authorization
  • Request deadlines
  • Error handling
  • Consistency expectations

The gateway should remain focused on edge concerns rather than becoming a general-purpose business orchestration layer.

The need for dedicated backend-for-frontend or application composition components will be evaluated separately.

Internal Services Must Remain Protected

Internal business service endpoints must not be publicly reachable by default.

External access must be restricted to approved entry points.

Internal services must authenticate and authorize protected service-to-service requests as required by ADR-0005 and ADR-0006.

Network restrictions and gateway routing do not replace service-level security enforcement.

The architecture must support defense in depth through appropriate combinations of:

  • Network access restrictions
  • Workload authentication
  • Authorization
  • Organization context validation
  • Resource ownership enforcement
  • Secure transport

The specific networking, service discovery, ingress, and transport security mechanisms will be selected separately.

Observability and Traceability Must Be Preserved

The gateway must support consistent observability for external API requests.

Relevant information may include:

  • Request identifiers
  • Distributed trace context
  • API operation
  • Response status
  • Request duration
  • Authentication outcome
  • Rate-limiting decisions
  • Upstream dependency failures

Request correlation must be preserved across gateway and service boundaries.

Observability must support investigation of:

  • Elevated API latency
  • Increased error rates
  • Authentication failures
  • Authorization denials
  • Rate-limit violations
  • Upstream service failures
  • Timeout patterns

Logs and traces must not expose credentials, secrets, sensitive business data, or unauthorized organization information.

Organization identifiers may be included in appropriately protected structured logs and traces when needed for observability or troubleshooting.

Unbounded organization-level dimensions should not be added indiscriminately to metrics.

Gateway Availability Must Be Protected

Because the API Gateway is a shared external entry point, its availability is important to overall platform accessibility.

The architecture must support appropriate resilience and operational safeguards.

These may include:

  • Multiple gateway instances
  • Health checks
  • Readiness checks
  • Controlled deployments
  • Capacity management
  • Load balancing
  • Graceful connection handling
  • Dependency timeouts
  • Resource limits
  • Monitoring and alerting

Gateway failures must not result in authentication or authorization bypasses.

Failure of one backend service must not prevent access to unrelated healthy services.

The gateway must avoid unbounded retries, excessive buffering, or resource consumption that could amplify backend failures.

Detailed deployment topology, scaling policies, and resilience mechanisms will be defined separately.

Rationale

Provide a Consistent External Entry Point

A centralized gateway simplifies client connectivity and provides a controlled interface to Zelvoryqa capabilities.

Preserve Business Service Ownership

Keeping business logic and authoritative data within their owning services prevents the gateway from becoming a centralized application monolith.

Strengthen Security Boundaries

Centralized edge authentication and traffic controls complement service-level authorization and tenant isolation.

Reduce Client Coupling

Clients interact with stable external contracts rather than internal service topology or communication protocols.

Support Independent Service Evolution

Services may evolve internally without requiring equivalent changes to external clients when public contract compatibility is preserved.

Improve Operational Visibility

A shared entry point supports consistent traffic monitoring, request correlation, and infrastructure-level error handling.

Support Multi-Tenant Traffic Management

Organization-aware quotas and traffic controls can help protect shared platform resources and reduce cross-tenant interference.

Alternatives Considered

Alternative 1: Expose Each Business Service Directly

External clients communicate directly with individual business services.

Advantages

  • Fewer centralized routing components
  • Direct client-to-service communication
  • Reduced gateway infrastructure requirements

Disadvantages

  • Exposes more internal service boundaries
  • Increases client coupling to service topology
  • Duplicates common edge concerns
  • Complicates consistent authentication and traffic controls
  • Increases external API management complexity

Reason Not Selected

Zelvoryqa requires a consistent and controlled external API entry point without exposing internal service topology by default.

Alternative 2: Implement All External APIs in a Centralized Backend

A single centralized backend owns external APIs and implements business operations across domains.

Advantages

  • Centralized client-facing implementation
  • Simple initial routing
  • Fewer distributed API boundaries

Disadvantages

  • Concentrates business logic
  • Weakens service autonomy
  • Risks bypassing authoritative service ownership
  • Creates a large coordination and deployment boundary
  • Conflicts with the capability-oriented microservices architecture

Reason Not Selected

Zelvoryqa requires independent business capability ownership and service-level enforcement.

Alternative 3: Use a Centralized API Gateway with Service-Owned APIs

External clients access business capabilities through a shared gateway that routes requests to independently owned service APIs.

Advantages

  • Consistent external entry point
  • Centralized edge traffic controls
  • Reduced exposure of internal services
  • Preserves service ownership
  • Supports stable external contracts
  • Enables request correlation and centralized observability
  • Supports multi-tenant traffic management

Disadvantages

  • Introduces shared gateway infrastructure
  • Requires gateway availability planning
  • Adds routing and configuration management
  • May introduce additional request latency
  • Requires clear separation between edge and business responsibilities

Reason Selected

This approach provides a consistent external API architecture while preserving Zelvoryqa service boundaries, security responsibilities, and independent evolution.

Consequences

Positive Consequences

  • External clients use controlled API entry points.
  • Internal services are not publicly exposed by default.
  • External API contracts can remain stable as internal implementations evolve.
  • Common edge concerns are handled consistently.
  • Business services retain authoritative ownership.
  • Gateway authentication complements service-level authorization.
  • Organization context is preserved across request boundaries.
  • API versioning and compatibility become explicit requirements.
  • Traffic controls can protect shared infrastructure.
  • Observability and request tracing are consistent across external APIs.

Negative Consequences

  • The gateway becomes shared operational infrastructure.
  • Gateway configuration and deployment require management.
  • An additional network hop may increase request latency.
  • Authentication and organization context propagation require careful design.
  • External contract compatibility must be maintained.
  • Rate limiting and quotas require operational policies.
  • API composition may require additional components.
  • Gateway and backend failure handling require coordination.

Risks

  • Gateway becoming a single point of failure
  • Business logic accumulating in the gateway
  • Overly broad routing rules
  • Unauthorized access through incorrectly trusted headers
  • Inconsistent organization context propagation
  • Reliance on gateway-only authorization
  • Public exposure of internal service endpoints
  • Breaking changes to external contracts
  • Incorrect timeout and retry behavior
  • Excessive gateway resource consumption
  • Cross-tenant interference from unbounded traffic
  • Sensitive information exposure through logs or errors
  • Tight coupling between public APIs and internal service implementations

Implementation Considerations

Future implementation must define:

  • API Gateway technology
  • External ingress and routing configuration
  • External authentication integration
  • Trusted identity context propagation
  • Organization context representation
  • API endpoint conventions
  • HTTP request and response schemas
  • API documentation format
  • API versioning rules
  • Error response envelopes
  • Request validation conventions
  • Rate limiting and quota policies
  • Request timeout policies
  • Idempotency and retry contracts
  • API composition requirements
  • Long-running operation contracts
  • Internal service discovery
  • Secure transport configuration
  • Gateway observability
  • Gateway deployment and scaling
  • External API testing and contract validation

Implementation choices must preserve the requirements established by this ADR.

Operational Considerations

The API Gateway is a shared entry point and must be operated as a critical platform component.

Operational monitoring must support investigation of:

  • Gateway availability
  • Request latency
  • Error rates
  • Authentication failures
  • Authorization denials
  • Rate limiting
  • Backend service failures
  • Request timeouts
  • Connection failures
  • Traffic spikes
  • Resource saturation
  • Routing failures

Operational procedures must account for:

  • Gateway deployment failures
  • Configuration errors
  • Authentication dependency outages
  • Backend service outages
  • Traffic surges
  • Credential compromise
  • Certificate expiration
  • Capacity exhaustion
  • Incident response
  • Rollback and recovery

Gateway configuration changes must be validated before deployment.

Security-sensitive gateway configuration must be managed through controlled deployment processes.

Monitoring should distinguish between gateway-originated failures and failures returned by downstream services.

The gateway must preserve appropriate request correlation information to support end-to-end troubleshooting.

Validation

This decision will be considered successfully implemented when Zelvoryqa can demonstrate that:

  • External clients access protected business APIs through approved entry points.
  • Internal business services are not publicly reachable by default.
  • External API contracts are explicitly documented.
  • External APIs use consistent HTTP-based resource interfaces.
  • Protected requests require appropriate authentication.
  • Client-provided identity and organization information are not blindly trusted.
  • Organization context is validated and propagated appropriately.
  • Business services enforce their own authorization and resource ownership requirements.
  • Gateway authorization does not replace service-level authorization.
  • Gateway validation does not replace business validation.
  • External API versioning and compatibility rules are defined.
  • Error responses follow documented external contracts.
  • State-changing operations support appropriate retry and idempotency behavior.
  • Request deadlines and cancellation are handled consistently.
  • Rate limiting and abuse protection are supported.
  • API composition does not bypass authoritative service ownership.
  • Internal service communication remains protected.
  • Request identifiers and distributed trace context are preserved.
  • Sensitive information is not unnecessarily exposed in logs or errors.
  • Gateway failures do not result in security bypasses.
  • Gateway and backend failures can be monitored and diagnosed.
  • Relevant architectural requirements are covered by automated tests.

Follow-Up

Additional architectural decisions will define:

  • API Gateway and ingress technology selection
  • External API contract and documentation standards
  • API versioning and compatibility policies
  • Identity provider and authentication protocol selection
  • Organization context propagation mechanisms
  • Internal service communication protocol selection
  • Rate limiting and tenant quota policies
  • API composition and backend-for-frontend requirements
  • Long-running operation patterns
  • Gateway deployment, scaling, and resilience
  • External API observability and audit requirements

References

  • ADR-0001: Adopt Microservices Based on Business Capabilities
  • ADR-0002: Adopt Multi-Tenant SaaS Architecture
  • ADR-0003: Define Service Data Ownership and Tenant Data Isolation
  • ADR-0004: Adopt Event-Driven Integration
  • ADR-0005: Define Synchronous Service Communication
  • ADR-0006: Define Authentication, Organization Membership, and Authorization
  • Zelvoryqa Architecture Overview
  • Zelvoryqa Product Vision
  • Zelvoryqa Goals

Status Definitions

  • Proposed — The decision is under review.
  • Accepted — The decision has been approved and should guide implementation.
  • Deprecated — The decision is no longer recommended but remains for historical context.
  • Superseded — The decision has been replaced by a newer ADR.

ADR Guidelines

This ADR records one significant architectural decision.

The ADR should:

  • Explain the context that required the decision.
  • State the decision clearly.
  • Document the reasoning behind the decision.
  • Record meaningful alternatives and tradeoffs.
  • Separate durable architectural requirements from implementation details.
  • Avoid selecting technologies that belong in later decisions.
  • Be superseded rather than rewritten when the architectural decision fundamentally changes.