Pro RSS API: design a predictable interface for feed records

Separate source facts from processing facts

Keep the publisher's title, article link, and supplied publication date together with a source identifier. Store observation time, processing status, and normalization version separately. This prevents a client from treating the last fetch as the article's publication event. Document missing values and preserve uncertainty when a source supplies incomplete metadata.

A useful proposed record might contain source_id, item_id, title, url, published_at, and observed_at. These names are illustrative design choices. Choose fields that solve the consumer's task, then keep their meanings stable across releases. Add output schema validation before the response leaves the adapter.

Bound the work behind a request

Decide whether clients read a prepared snapshot or trigger a refresh. A snapshot can make response behavior easier to control, while a refresh introduces upstream delays and failures into the request path. If collection is asynchronous, expose the last successful update and current processing state so the client can communicate age accurately.

• Limit page size and define a stable ordering with a deterministic tie-breaker for equal dates.
• Choose a pagination approach that handles new arrivals without silently dropping or duplicating records.
• Keep source selection within an approved registry instead of accepting arbitrary network destinations.
• State whether partial results are allowed and how excluded items or failed sources are reported.

Make errors useful to application developers

Distinguish an unknown source, an unsupported feed format, a temporary upstream problem, and an invalid request. Return stable reason codes with concise explanations. Avoid exposing raw parser output, private source addresses, or access credentials. A successful response with zero items should have a different meaning from a refresh that failed before any records could be inspected.

Review an example consumer

Imagine a newsroom dashboard that displays the latest approved items. Its acceptance exercise should include a new item, a corrected title, an unavailable publisher, and a page boundary reached while another item arrives. Check the rendered result and the underlying record identifiers. Save those expectations with the contract so future changes preserve the dashboard's behavior. An API becomes dependable through explicit semantics, bounded work, and consumers that can explain the data they receive.

Primary documentation

• RFC 9110: HTTP Semantics
• RSS 2.0 Specification