diff --git a/astro.config.ts b/astro.config.ts index ae8e0c73..0da02cfd 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -7,6 +7,10 @@ export default defineConfig({ starlight({ title: "Open Podcast API", favicon: "favicon.ico", + customCss: ["styles/API-classification.css"], + components: { + Banner: "./src/components/Banner.astro", + }, social: [ { icon: "github", @@ -41,8 +45,21 @@ export default defineConfig({ label: "Introduction", link: "specs", }, + { + label: "Conventions", + collapsed: true, + items: [{ + autogenerate: { + directory: "specs/conventions", + } + }], + }, { label: "Subscriptions", + badge: { + text: "C", + class: "core", + }, collapsed: true, items: [{ autogenerate: { diff --git a/src/components/Banner.astro b/src/components/Banner.astro new file mode 100644 index 00000000..af806c6d --- /dev/null +++ b/src/components/Banner.astro @@ -0,0 +1,23 @@ +--- +import { apiClassificationBanners } from '../data/banners'; + +const { apiClassification } = Astro.locals.starlightRoute.entry.data; +const content = apiClassification ? apiClassificationBanners[apiClassification] : undefined; +--- + +{content &&
{content}
} + + \ No newline at end of file diff --git a/src/content.config.ts b/src/content.config.ts index 1e3e4cf9..93d250ce 100644 --- a/src/content.config.ts +++ b/src/content.config.ts @@ -1,8 +1,21 @@ import { defineCollection } from 'astro:content'; +import { z } from 'astro/zod'; import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; import { docsLoader } from '@astrojs/starlight/loaders'; export const collections = { - docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }), + docs: defineCollection({ + loader: docsLoader(), + schema: docsSchema({ + extend: z.object({ + apiClassification: z.enum([ + 'core-endpoint', + 'optional-endpoint', + 'core-action', + 'optional-action', + ]).optional(), + }), + }), + }), i18n: defineCollection({ type: 'data', schema: i18nSchema() }), }; diff --git a/src/content/docs/specs/conventions/client-ids.md b/src/content/docs/specs/conventions/client-ids.md new file mode 100644 index 00000000..7def705c --- /dev/null +++ b/src/content/docs/specs/conventions/client-ids.md @@ -0,0 +1,30 @@ +--- +title: Client IDs +description: Conventions for identifying clients that interact with the Open Podcast API. +sidebar: + order: 4 +--- + +Each client must generate and persist a [UUIDv4](https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-4) value that uniquely identifies that client installation or instance. Client IDs identify a client installation rather than a user or device. + +Include this value with every API request using the `Client-ID` header. + +```txt +Client-ID: 550e8400-e29b-41d4-a716-446655440000 +``` + +:::note +The client ID is used only to identify the source of synchronized changes. It is not an authentication credential and can be freely regenerated if the client state is reset. +::: + +## Requirements + +* Generate the ID once, when the client is first initialized. +* The ID must be a valid UUID version 4 (random UUID). +* Persist the ID and reuse it for all future requests. +* Do not generate a new ID for each request. +* Each independent client installation or instance should have its own unique ID. + +## Purpose + +The server uses the client ID to identify the origin of changes. Endpoints that return updates can exclude changes created by the requesting client, allowing clients to synchronize only updates originating from other clients. \ No newline at end of file diff --git a/src/content/docs/specs/conventions/core-and-optional-functionality.mdx b/src/content/docs/specs/conventions/core-and-optional-functionality.mdx new file mode 100644 index 00000000..d9648458 --- /dev/null +++ b/src/content/docs/specs/conventions/core-and-optional-functionality.mdx @@ -0,0 +1,15 @@ +--- +title: Core and optional functionality +description: Conventions for distinguishing core and optional functionality in the Open Podcast API. +sidebar: + order: 3 +--- + +import { Badge } from '@astrojs/starlight/components'; + +To ensure that the end-user experience is consistent across implementations, the specifications mark endpoints and features as (required) and . + +* : The feature or endpoint MUST be supported by all clients and servers. +* : The feature or endpoint is considered to be additional functionality. + +Clients and servers may optionally support any combination of these features. Any project implementing Optional functionality should inform users about what is supported. \ No newline at end of file diff --git a/src/content/docs/specs/conventions/index.md b/src/content/docs/specs/conventions/index.md new file mode 100644 index 00000000..aa8ecb4b --- /dev/null +++ b/src/content/docs/specs/conventions/index.md @@ -0,0 +1,21 @@ +--- +title: Open Podcast API conventions +description: Practices and policies that apply to the full Open Podcast API. +prev: false +sidebar: + label: Overview + order: 1 +--- + +The following conventions are used for all endpoints in the Open Podcast API specification: +* Core and optional functionality +* Synchronization model + * Client behavior + * Server behavior +* Client IDs +* Timestamps & modifications +* Requests + * Content type +* Responses + * Response codes + * Pagination \ No newline at end of file diff --git a/src/content/docs/specs/conventions/requests.md b/src/content/docs/specs/conventions/requests.md new file mode 100644 index 00000000..c1b5a0e3 --- /dev/null +++ b/src/content/docs/specs/conventions/requests.md @@ -0,0 +1,14 @@ +--- +title: Requests +description: Conventions for requests made to the Open Podcast API. +sidebar: + order: 6 +--- + +## Content type + +All endpoints covered by the Open Podcast API require a `Content-Type` header to request JSON information from the server. + +```txt +Content-Type: application/json +``` \ No newline at end of file diff --git a/src/content/docs/specs/conventions/responses.md b/src/content/docs/specs/conventions/responses.md new file mode 100644 index 00000000..b846cd85 --- /dev/null +++ b/src/content/docs/specs/conventions/responses.md @@ -0,0 +1,21 @@ +--- +title: Responses +description: Conventions for responses returned by the Open Podcast API. +sidebar: + order: 7 +--- + +## Response codes + +The Open Podcast API uses the following HTTP response codes: + +* `200`: operation completed successfully. +* `400`: the client sent an invalid request. +* `401`: the client attempted to request a resource without authentication. +* `403`: the client requested access to a resource it does not have permission to interact with. +* `404`: the client attempted to access a non-existent resource. +* `500`: the server encountered an error while performing a request. + +## Pagination + +All bulk `GET` requests must be paginated using a stable offset value. For the sync endpoint, this value must be a UTC timestamp in the RFC3339 format. For bulk entity endpoints, the entity ID or another stable incremental value should be used. The server must respond with navigation links in each response to point clients to the next and previous pages of results. \ No newline at end of file diff --git a/src/content/docs/specs/conventions/synchronization-model.md b/src/content/docs/specs/conventions/synchronization-model.md new file mode 100644 index 00000000..ef531282 --- /dev/null +++ b/src/content/docs/specs/conventions/synchronization-model.md @@ -0,0 +1,24 @@ +--- +title: Synchronization model +description: Conventions for synchronizing data between Open Podcast API clients and servers. +sidebar: + order: 2 +--- + +The Open Podcast API follows a batch synchronization model through a [synchronization endpoint](/specs/sync). Updates are processed in bulk using action names and entity types as discriminators. To reduce the risk of performance degradation while facilitating bulk updates from clients, updates are limited to 30 actions per request. + +## Client behavior + +Synchronization of data is based on client timestamps. These are considered authoritative. When a user performs an action on a client, the client must record the UTC timestamp of the action and send it with the corresponding update action. + +The client may send multiple bulk requests in sequence, starting from the earliest recorded timestamp. Requests are expected to be sent in chronological order. + +## Server behavior + +The server modifies state based on a last-write-wins model where the action with the latest timestamp always applies. + +The server must disregard any actions with a timestamp earlier than the current modification timestamp as stale. The server must always return the current canonical state of the requested entity whether the action was applied or not. + +Clients may request information from a given offset timestamp to fetch all relevant updates that have occurred since their last sync. Servers must respond only with entities that have been updated since the offset timestamp. The [client ID](../client-ids) of the client that made the most recent change to an entity must be preserved and only updates not made by the requesting client should be returned. + +In addition to the central sync endpoint, all entities must be made available for retrieval from domain-specific endpoints. Servers must provide bulk and single-item endpoints for each entity type. diff --git a/src/content/docs/specs/conventions/timestamps-and-modifications.md b/src/content/docs/specs/conventions/timestamps-and-modifications.md new file mode 100644 index 00000000..1c8a96d1 --- /dev/null +++ b/src/content/docs/specs/conventions/timestamps-and-modifications.md @@ -0,0 +1,30 @@ +--- +title: Timestamps & modifications +description: Conventions for timestamps and tracking modifications in the Open Podcast API. +sidebar: + order: 5 +--- + +## Timestamps + +:::caution[Important] +The synchronization protocol assumes that client clocks are reasonably accurate. Devices with significantly incorrect clocks may observe unexpected synchronization order. +::: + +All actions sent to the server must include a UTC timestamp recorded by the client. These timestamps determine action order. The server compares the client-supplied timestamp with the entity's current modification timestamp. An action with a later timestamp MUST be applied. An action with an earlier timestamp MUST be ignored. + +Timestamps must be submitted in the [RFC3339 format](https://www.rfc-editor.org/rfc/rfc3339). Servers must accept any fractional precision. For example: + +* `2026-07-11T15:30:00Z` +* `2026-07-11T15:30:00.1Z` +* `2026-07-11T15:30:00.123456Z` + +Once generated, an action's timestamp must not be modified. Retried requests must preserve the original timestamp. + +Actions contained within a batch are independent. Servers must order actions solely according to their timestamps rather than the order in which they appear in the request. + +An action is applied only if its timestamp is strictly later than the entity's current `last_updated` timestamp. Actions with an earlier or identical timestamp are ignored. + +## Modifications + +For each entity, servers must keep track of the `last_updated` timestamp and associated requesting client ID when a change is made to the entity metadata. When a client requests a sync response, any entity that has been modified by a different client must be returned. \ No newline at end of file diff --git a/src/content/docs/specs/subscriptions/add-new.mdx b/src/content/docs/specs/subscriptions/add-new.mdx index a94e28b8..d57c4cd9 100644 --- a/src/content/docs/specs/subscriptions/add-new.mdx +++ b/src/content/docs/specs/subscriptions/add-new.mdx @@ -3,13 +3,14 @@ title: Add a new subscription description: Add a new subscription sidebar: order: 2 + badge: + text: C + class: core +apiClassification: core-endpoint --- -import CoreAction from "@partials/_core-action.mdx"; import { Tabs, TabItem } from '@astrojs/starlight/components'; - - ```http title="Endpoint" POST /v1/subscriptions ``` diff --git a/src/content/docs/specs/subscriptions/delete.mdx b/src/content/docs/specs/subscriptions/delete.mdx index c9008739..7cdb9b56 100644 --- a/src/content/docs/specs/subscriptions/delete.mdx +++ b/src/content/docs/specs/subscriptions/delete.mdx @@ -3,13 +3,14 @@ title: Delete a subscription description: Fetch the status of a deletion process sidebar: order: 6 + badge: + text: C + class: core +apiClassification: core-action --- -import CoreAction from "@partials/_core-action.mdx"; import { Tabs, TabItem } from '@astrojs/starlight/components'; - - ```http title="Endpoint" DELETE /v1/subscriptions/{guid} ``` diff --git a/src/content/docs/specs/subscriptions/get-all.mdx b/src/content/docs/specs/subscriptions/get-all.mdx index 3a80a2ba..6ae17172 100644 --- a/src/content/docs/specs/subscriptions/get-all.mdx +++ b/src/content/docs/specs/subscriptions/get-all.mdx @@ -3,13 +3,14 @@ title: Get all subscriptions description: Get all subscriptions for a user sidebar: order: 3 + badge: + text: C + class: core +apiClassification: core-action --- -import CoreAction from "@partials/_core-action.mdx"; import { Tabs, TabItem } from '@astrojs/starlight/components'; - - ```http title="Endpoint" GET /v1/subscriptions ``` diff --git a/src/content/docs/specs/subscriptions/get-single.mdx b/src/content/docs/specs/subscriptions/get-single.mdx index 9a83b2e6..528cc22c 100644 --- a/src/content/docs/specs/subscriptions/get-single.mdx +++ b/src/content/docs/specs/subscriptions/get-single.mdx @@ -3,13 +3,14 @@ title: Get a single subscription description: Get a single subscription for a user sidebar: order: 4 + badge: + text: C + class: core +apiClassification: core-action --- -import CoreAction from "@partials/_core-action.mdx"; import { Tabs, TabItem } from '@astrojs/starlight/components'; - - ```http title="Endpoint" GET /v1/subscriptions/{guid} ``` diff --git a/src/content/docs/specs/subscriptions/index.mdx b/src/content/docs/specs/subscriptions/index.mdx index a6975902..5aee22eb 100644 --- a/src/content/docs/specs/subscriptions/index.mdx +++ b/src/content/docs/specs/subscriptions/index.mdx @@ -5,12 +5,9 @@ prev: false sidebar: label: Overview order: 1 +apiClassification: core-endpoint --- -import CoreEndpoint from "@partials/_core-endpoint.mdx"; - - - The subscriptions endpoint is used to synchronize subscriptions between a server and connected clients. The server is treated as the authoritative source for subscription information. Clients can query the endpoint by specifying the datetime from which they want to fetch changes to ensure they only fetch information that is relevant to them since their last sync. Subscriptions represent the feeds a user has subscribed to. A subscription object stores essential information about each subscription and acts as an index that links other activity information together. diff --git a/src/content/docs/specs/subscriptions/status.mdx b/src/content/docs/specs/subscriptions/status.mdx index d5705f51..9f98732d 100644 --- a/src/content/docs/specs/subscriptions/status.mdx +++ b/src/content/docs/specs/subscriptions/status.mdx @@ -3,13 +3,14 @@ title: Deletion status endpoint description: Fetch the status of a deletion process sidebar: order: 7 + badge: + text: C + class: core +apiClassification: core-action --- -import CoreAction from "@partials/_core-action.mdx"; import { Tabs, TabItem } from '@astrojs/starlight/components'; - - ```http title="Endpoint" GET /v1/deletions/{id} ``` diff --git a/src/content/docs/specs/subscriptions/update.mdx b/src/content/docs/specs/subscriptions/update.mdx index 136f8375..9f1d71c8 100644 --- a/src/content/docs/specs/subscriptions/update.mdx +++ b/src/content/docs/specs/subscriptions/update.mdx @@ -3,13 +3,14 @@ title: Update a subscription description: Update details about a subscription sidebar: order: 5 + badge: + text: C + class: core +apiClassification: core-action --- -import CoreAction from "@partials/_core-action.mdx"; import { Tabs, TabItem } from '@astrojs/starlight/components'; - - ```http title="Endpoint" PATCH /v1/subscriptions/{guid} ``` diff --git a/src/data/banners.ts b/src/data/banners.ts new file mode 100644 index 00000000..7cf495e0 --- /dev/null +++ b/src/data/banners.ts @@ -0,0 +1,6 @@ +export const apiClassificationBanners = { + 'core-endpoint': 'This is a core endpoint. All implementing servers and clients MUST support it.', + 'optional-endpoint': 'This is an optional endpoint.', + 'core-action': 'This is a core action. All implementing servers and clients MUST support it.', + 'optional-action': 'This is an optional action.', +} as const; \ No newline at end of file diff --git a/styles/API-classification.css b/styles/API-classification.css new file mode 100644 index 00000000..e61d3a93 --- /dev/null +++ b/styles/API-classification.css @@ -0,0 +1,22 @@ +.sl-badge.core, +.sl-banner.core-endpoint, +.sl-banner.core-action { + background-color: var(--sl-color-green-low); + border-color: var(--sl-color-green); + color: var(--sl-color-green-high); +} + +.sl-badge.optional, +.sl-banner.optional-endpoint, +.sl-banner.optional-action { + background-color: var(--sl-color-blue-low); + border-color: var(--sl-color-blue); + color: var(--sl-color-blue-high); +} + +.sl-banner.core-endpoint, +.sl-banner.core-action, +.sl-banner.optional-endpoint, +.sl-banner.optional-action { + box-shadow: none; +} \ No newline at end of file