Add Conventions section and Badges

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: {

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 && <div class={`sl-banner ${apiClassification}`} data-pagefind-ignore>{content}</div>}
+
+<style>
+	@layer starlight.core {
+		.sl-banner {
+			--__sl-banner-text: var(--sl-color-banner-text, var(--sl-color-text-invert));
+			padding: var(--sl-nav-pad-y) var(--sl-nav-pad-x);
+			background-color: var(--sl-color-banner-bg, var(--sl-color-bg-accent));
+			color: var(--__sl-banner-text);
+			line-height: var(--sl-line-height-headings);
+			text-align: center;
+			text-wrap: balance;
+			box-shadow: var(--sl-shadow-sm);
+		}
+	}
+</style>

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() }),
 };

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.

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 <Badge text="Core" class="core" size="small" /> (required) and <Badge text="Optional" class="optional" size="small" />.
+
+* <Badge text="Core" class="core" size="small" />: The feature or endpoint MUST be supported by all clients and servers.
+* <Badge text="Optional" class="optional" size="small" />: 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.

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

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
+```

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.

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.

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.

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';
 
-<CoreAction />
-
 ```http title="Endpoint"
 POST /v1/subscriptions
 ```

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';
 
-<CoreAction />
-
 ```http title="Endpoint"
 DELETE /v1/subscriptions/{guid}
 ```

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';
 
-<CoreAction />
-
 ```http title="Endpoint"
 GET /v1/subscriptions
 ```

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';
 
-<CoreAction />
-
 ```http title="Endpoint"
 GET /v1/subscriptions/{guid}
 ```

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";
-
-<CoreEndpoint />
-
 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.

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';
 
-<CoreAction />
-
 ```http title="Endpoint"
 GET /v1/deletions/{id}
 ```

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';
 
-<CoreAction />
-
 ```http title="Endpoint"
 PATCH /v1/subscriptions/{guid}
 ```

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;