Skip to content

api-catalog.md

Latest commit

 

History

History
82 lines (70 loc) · 4.42 KB

api-catalog.md

File metadata and controls

82 lines (70 loc) · 4.42 KB
Raw

API Catalog

Every EOEPCA+ deployment exposes a machine-readable directory of its services at /.well-known/api-catalog. User clients treat this as the only supported way to discover endpoints, authentication, and deployment metadata, they MUST NOT hard-code service URLs or assume a fixed hostname layout.

RFC 9727 well-known URI, RFC 9264 Linkset JSON (application/linkset+json). Services are link targets keyed by link relation type (rel); relation URIs and extension properties are in schema/v1.json.

check-jsonschema --schemafile docs/api/schema/v1.json docs/api/schema/example.json

Deployments MUST serve a document that validates against the current schema. Clients SHOULD fetch service-desc from the catalog for the live schema URL. Look services up by rel. Absent eoepca:auth, means unauthenticated access is possible.

!!! note The develop deployment does not serve /.well-known/api-catalog yet; schema/example.json is the reference document until it does.

Selecting among multiple targets

A rel may list several targets (e.g. data carries both an open resource catalogue and a transactional eoAPI STAC). Clients that need write access SHOULD prefer the target whose conformsTo includes a STAC API core conformance class and whose eoepca:auth is oidc-write, falling back to the first STAC-conformant target otherwise.

Known service behaviours

  • eoAPI on develop accepts any token whose aud claim contains eoapi (eoepca:default_client_id above) — not only tokens whose azp literally equals eoapi. A token obtained from a different OIDC client (e.g. workspace-api) works fine as long as eoapi is one of its audiences; see the client_id note below for why that matters in practice.
  • eoAPI answers item DELETE with 200 and a JSON body rather than 204.
  • eoAPI item write (POST .../items) requires bbox whenever geometry is not null, including for degenerate geometries like a single Point (use e.g. [lon, lat, lon, lat]) — the STAC core spec technically already requires this, but it's easy to omit for a minimal test item.
  • The openeo rel's titiler-openeo backend requires a bearer token on POST /result even though the rel declares no eoepca:auth — absence of that field is not a reliable "unauthenticated is fine" signal for this service.
  • workspace-api requires a token audienced for its own OIDC client, not just any authenticated realm token — eoepca:default_client_id (eoapi) produces a token that workspace-api's gateway rejects outright with {"detail":"Invalid token audience"}. Logging in via the workspace-api client instead yields a token whose aud is a superset (workspace-api, eoapi, the user's own workspace name, zoo, account) that satisfies STAC, workspace-api, and openEO simultaneously — this is why eoepca-client's develop profile authenticates as workspace-api, not eoapi, despite the catalog's advertised default. The catalog currently has no per-rel way to express "authenticate as this other client for this target" — worth a schema addition if more audience-scoped services show up.
  • s3 targets with "eoepca:virtual_hosting": false require path-style bucket addressing (https://<endpoint>/<bucket>/<key>); virtual-hosted style (https://<bucket>.<endpoint>/<key>) fails outright against these deployments (TLS certificate doesn't cover the bucket subdomain).
  • On develop, all S3 uploads currently fail with 413 regardless of file size — the MinIO ingress has APISIX's client-control plugin configured with max_body_size: 0 (almost certainly meant as "no limit" but which APISIX interprets as "reject any non-empty body"). This is a platform-side misconfiguration, not fixable from the client; downloads and listing are unaffected since they carry no request body.

Versioning

eoepca:schema_version is SemVer. Changes within a MAJOR are additive only. On a MAJOR bump the previous schema stays available at its versioned URL (e.g. /schemas/discovery/v1.json) and the new one is published alongside it; deployments state the version they implement in eoepca:schema_version.