[RFD]: Standardized OpenAPI Discovery Endpoint for OpenCHAMI

[alexlovelltroy]

Decision Goal

Define a consistent, machine-discoverable endpoint for retrieving OpenAPI specifications across all OpenCHAMI services using a .well-known URI pattern. This enables dynamic client generation, federation-aware tooling, and consistent service introspection without prior knowledge of service-specific paths.

Category

Architecture

Stakeholders / Affected Areas

No response

Decision Needed By

No response

Problem Statement

Motivation

OpenCHAMI is evolving toward:

• Federated control planes
• Schema-driven APIs
• Dynamic clients (CLI, UI, automation)

Current state:

• OpenAPI endpoints are inconsistent or implicit
• Clients must be preconfigured with service-specific URLs
• No uniform way to introspect capabilities across services

This creates friction for:

• CLI tooling (e.g., ochami)
• Cross-service orchestration
• External integrations
• Future multi-cluster federation

---

Problem Statement

There is no standardized way within OpenCHAMI to:

• Discover API schemas programmatically
• Enumerate available API groups or versions
• Support tooling that can adapt dynamically to deployed services

This mirrors the broader ecosystem gap where the OpenAPI Specification defines format but not discovery.

Proposed Solution

Adopt a .well-known discovery endpoint for all OpenCHAMI services.

Base Endpoint

GET /.well-known/openapi

Returns:

• Default OpenAPI document for the service
• Typically the latest stable version

---

Query Parameters

Support optional filtering:

GET /.well-known/openapi?group=<group>&version=<version>

Examples:

/.well-known/openapi?group=inventory
/.well-known/openapi?group=boot&version=v1

---

Response

• application/json
• Valid OpenAPI 3.x document
• May be generated dynamically or served statically

---

Optional Index Endpoint

To support discovery of available groups and versions:

GET /.well-known/openapi/index

Example response:

{
  "groups": [
    {
      "name": "inventory",
      "versions": ["v1", "v2"]
    },
    {
      "name": "boot",
      "versions": ["v1"]
    }
  ]
}

---

Design Considerations

Alignment with Existing Standards

• Uses .well-known pattern defined in RFC 5785
• Mirrors discovery models used in OIDC and ACME
• Does not conflict with existing OpenAPI tooling

---

Backward Compatibility

• Does not replace existing endpoints (/openapi.json, /v3/api-docs, etc.)
• Services may continue exposing legacy paths
• .well-known endpoint acts as a stable overlay

---

Implementation Flexibility

Services may:

• Serve static OpenAPI files
• Generate specs dynamically from schema definitions
• Proxy or aggregate multiple internal APIs

---

Federation Implications

Supports:

• Cross-cluster API discovery
• Dynamic federation clients
• Capability negotiation between control planes

Alternatives Considered

1. Do nothing

   • Maintains current inconsistency
   • Prevents dynamic tooling

2. Framework-specific conventions

   • Locks OpenCHAMI into specific stacks
   • Reduces portability

3. Central registry only

   • Adds operational complexity
   • Creates a single point of failure
   • Limits decentralized discovery

Other Considerations

No response

Related Docs / PRs

No response

[synackd]

I think implementing RFC 8615 (obsoletes RFC 5785) for all services is a good idea. Having (an) endpoint(s) under /.well-known/ for OpenAPI would provide a standard way for API discovery and could provide an interactive way to test the API via the OpenAPI UI.

At first pass, I think having endpoints for both raw OpenAPI data (JSON at a minimum, but maybe YAML as well) and the OpenAPI interactive UI should be standard at a minimum to fulfill the purposes described above. As far as paths, they could look something like:

• /.well-known/docs/api: return full JSON of OpenAPI spec
  • Set Accept: application/yaml to return YAML, server should support
  • Query parameter support (e.g. group=, version= as described above)
• /.well-known/docs/api/index: return API index for discovry
• /.well-known/docs/api/ui: return OpenAPI interactive UI
  • Ideally auto-generated, e.g. with something like swag

I chose the above because it seems succinct and intuitive, but am open to other ideas.

[synackd]

Amending the above, it's worth noting that the IETF defines a list of registered well-known URIs. On the list is /.well-known/api-catalog, defined in RFC 9727 for API discovery.