Class: ApiCatalogController

Inherits:
ActionController::Base
  • Object
show all
Defined in:
app/controllers/api_catalog_controller.rb

Overview

Serves the RFC 9727 API Catalog plus its companion machine description and
human documentation, enabling automated discovery of WarmlyYours' public
API by crawlers and AI agents.

Three sibling endpoints, all mounted at the top level (ahead of the
subdomain-scoped draws) so they answer on every WarmlyYours origin —
mirroring /up and /robots.txt. A scanner pointed at any host (typically
www) therefore finds the catalog, while the catalog's links themselves
always point at the canonical API host (api.warmlyyours.com):

  1. API Catalog (RFC 9727) — GET /.well-known/api-catalog
    An application/linkset+json linkset (RFC 9264) with one entry per API.
    Each entry carries the API anchor plus the service-desc (OpenAPI),
    service-doc (human docs), and status (health) link relations.

  2. OpenAPI description (service-desc) — GET /openapi.json
    A minimal OpenAPI 3.1 document describing the genuinely public read
    endpoints (Google Merchant feeds, oEmbed, location lookups).

  3. Human docs (service-doc) — GET /api-docs
    A short, self-contained HTML page summarizing the same endpoints.

Inherits from ActionController::Base (not ApplicationController) so no
auth/locale/session filters run — the catalog must be reachable
unauthenticated on crm.* and api.* exactly as on www.*. Each document
is regenerated cheaply per request and cached at the edge via expires_in.

See Also:

Constant Summary collapse

CACHE_TTL =

Edge/browser cache TTL shared by all three documents. They change only on
deploy and are cheap to regenerate, so a modest public TTL is plenty.

1.hour

Instance Method Summary collapse

Instance Method Details

#docs ⇒ void

This method returns an undefined value.

Human-readable API documentation referenced by the service-doc relation.



58
59
60
61
62
 
# File 'app/controllers/api_catalog_controller.rb', line 58

def docs
  expires_in CACHE_TTL, public: true
  @api_base = api_base
  render :docs, layout: false
end

#openapi ⇒ void

This method returns an undefined value.

OpenAPI 3.1 description referenced by the catalog's service-desc relation.



51
52
53
 
# File 'app/controllers/api_catalog_controller.rb', line 51

def openapi
  render_document openapi_document, 'application/openapi+json'
end

#show ⇒ void

This method returns an undefined value.

RFC 9727 API Catalog, expressed as an RFC 9264 linkset.



44
45
46
 
# File 'app/controllers/api_catalog_controller.rb', line 44

def show
  render_document catalog_document, 'application/linkset+json'
end