weatherapi/docs/integrations/feedapi.md

Feedapi Runtime Contract

weatherapi uses feedapi as its generic HTTP runtime and configuration layer. This document describes the feedapi behavior that weatherapi relies on.

Version

go.mod depends on:

• gitea.maximumdirect.net/ejr/feedapi v0.1.0

Only feedapi behavior used by weatherapi is documented here.

Packages Used

Runtime composition imports:

• feedapi/app
• feedapi/config
• feedapi/db

The HTTP adapter imports:

• feedapi/bind
• feedapi/endpoint
• feedapi/errors
• feedapi/render
• feedapi/response

Tests also use:

• feedapi/templates
• feedapi/transport/httpx

Config Ownership

Feedapi owns loading and validating the YAML config used by weatherapi. weatherapi adds one local runtime check: databases must contain at least one entry.

The implemented config areas used by weatherapi are:

• server: HTTP listen/default format/timeouts;
• databases: named database handles opened into a registry;
• templates: base directory for text templates.

The canonical config reference is docs/config.md.

Database Registry

cmd/weatherapi calls feedapi db.OpenAll with configured databases and passes the resulting registry into feedapi/app.New. It also selects the first configured database name from the registry as the primary weather store.

Feedapi owns opening and closing database handles. weatherapi owns choosing which opened handle is used by the Postgres repository.

Endpoint Registry

weatherapi builds endpoint definitions with httpapi.Definitions and passes them to feedapi through feedapi/app.WithEndpoints.

Feedapi owns:

• route adaptation;
• HTTP method/path matching;
• invoking endpoint binders;
• invoking endpoint handlers;
• rendering handler results.

Endpoint definitions remain owned by internal/adapters/inbound/httpapi.

Renderers and Templates

Each implemented endpoint declares JSON, XML, and text output through feedapi render formats. Text endpoints also name a template file.

Feedapi owns:

• renderer registration;
• format negotiation;
• template loading from templates.base_dir;
• applying templates to response envelopes.

weatherapi owns the template files under templates/ and presenter output shapes consumed by those templates.

Content Negotiation

weatherapi relies on feedapi's negotiation order:

1. format query parameter;
2. Accept header;
3. configured default format.

Unsupported formats are exposed as structured API errors. See docs/api.md for the public HTTP contract.

Success and Error Envelopes

Endpoint handlers return response.Envelope{Data: ...} for successful responses. Nil data is rendered as data: null.

Feedapi error handling exposes structured error envelopes with:

• error.code;
• error.message.

weatherapi relies on feedapi invalid-parameter and unsupported-format errors for request validation and negotiation failures.

Middleware and Shutdown

Feedapi owns generic HTTP middleware and server lifecycle. The architecture policy records that recovery, request ID, and timing middleware are installed by default.

weatherapi supplies a signal-cancelable context to feedapi startup. Feedapi owns graceful HTTP shutdown after that context is canceled.

Upgrade Checklist

Before upgrading feedapi:

• verify config field names and defaults still match docs/config.md;
• verify database registry behavior still supports first configured database selection;
• verify endpoint definition APIs still support binders, handlers, formats, and template names;
• verify negotiation order remains format, then Accept, then default;
• verify success and error envelopes still match docs/api.md;
• run go test ./... with private module access configured.

Related Docs

• docs/internal/runtime.md
• docs/internal/http-adapter.md
• docs/api.md
• docs/config.md
• docs/operations.md