Versioning endpoints

astro.config.mjs

@@ -41,6 +41,13 @@ export default defineConfig({
               label: "Introduction",
               link: "specs",
             },
+            {
+              label: "Versioning",
+              collapsed: true,
+              autogenerate: {
+                directory: "specs/versioning",
+              },
+            },
             {
               label: "Subscriptions",
               collapsed: true,

schema.yml

@@ -7,8 +7,10 @@ info:
 tags:
   - name: Subscriptions
     description: All actions relating to subscription management
+  - name: Versions
+    description: All actions relating to supported versions and capabilities
 paths:
-  /subscriptions:
+  /v1/subscriptions:
     get:
       tags:
         - Subscriptions
@@ -78,7 +80,7 @@ paths:
       security:
         - podcast_auth:
             - write:subscriptions
-  /subscriptions/{guid}:
+  /v1/subscriptions/{guid}:
     get:
       tags:
         - Subscriptions
@@ -175,7 +177,7 @@ paths:
       security:
         - podcast_auth:
             - write:subscriptions
-  /deletions/{id}:
+  /v1/deletions/{id}:
     get:
       tags:
         - Subscriptions
@@ -202,6 +204,54 @@ paths:
       security:
         - podcast_auth:
             - read:subscriptions
+  /versions:
+    get:
+      tags:
+        - Versions
+      summary: Retrieve a list of supported versions
+      description: Retrieve a list of each supported major/minor version of the API from the server
+      operationId: getVersions
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VersionArray'
+            application/xml:
+              schema:
+                $ref: '#/components/schemas/VersionArray'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      security:
+        - podcast_auth:
+            - read:versions
+  /v1/capabilities:
+    get:
+      tags:
+        - Versions
+      summary: Retrieve a list of supported capabilities
+      description: Retrieve a list of each supported capabilties from the server
+      operationId: getCapabilities
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Capabilities'
+            application/xml:
+              schema:
+                $ref: '#/components/schemas/Capabilities'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      security:
+        - podcast_auth:
+            - read:versions
 components:
   responses:
     Unauthorized:
@@ -573,6 +623,38 @@ components:
         deletion_id: 25
         status: SUCCESS
         message: Subscription deleted successfully
+    VersionArray:
+      type: object
+      xml:
+        name: versions
+      additionalProperties:
+        $ref: "#/components/schemas/Version"
+      example:
+        v1: 6
+        v2: 0
+    Version:
+      xml:
+        name: version
+        attribute: true
+      type: number
+      format: integer
+
+    Capabilities:
+      type: object
+      xml:
+        name: root
+      properties:
+        capabilities:
+          type: object
+          additionalProperties:
+            type: object
+          example:
+            queue_sync:
+              max_queues: 5
+            store_shows: {}
+            store_episodes:
+              allow: true
+              upload_quota: 500
   requestBodies:
     FeedArray:
       description: An array of feeds the user wants to subscribe to
@@ -601,6 +683,8 @@ components:
           scopes:
             write:subscriptions: modify subscription information for your account
             read:subscriptions: read your subscription information
+            read:versions: read supported server versions
+            read:capabilities: read supported server capabilities
     api_key:
       type: apiKey
       name: api_key

src/components/NetlifyCallout.astro

@@ -0,0 +1,91 @@
+---
+interface Props {
+  title: string;
+}
+
+const { title } = Astro.props;
+---
+
+<article class="sl-flex" aria-labelledby="about-netlify-heading">
+  <small id="about-netlify-heading">
+    {title}
+    <span class="sr-only">Netlify</span>
+  </small>
+  <svg
+    width="512"
+    height="209"
+    viewBox="0 0 512 209"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <g clip-path="url(#clip0_235_8)">
+      <path
+        d="M117.436 207.036V154.604L118.529 153.51H129.452L130.545 154.604V207.036L129.452 208.13H118.529L117.436 207.036Z"
+        fill="#05BDBA"></path>
+      <path
+        d="M117.436 53.5225V1.09339L118.529 0H129.452L130.545 1.09339V53.5225L129.452 54.6159H118.529L117.436 53.5225Z"
+        fill="#05BDBA"></path>
+      <path
+        d="M69.9539 169.238H68.4094L60.6869 161.512V159.967L78.7201 141.938L86.8976 141.942L87.9948 143.031V151.209L69.9539 169.238Z"
+        fill="#05BDBA"></path>
+      <path
+        d="M69.9462 38.8917H68.4017L60.6792 46.6181V48.1626L78.7124 66.192L86.8899 66.1882L87.9871 65.0986V56.9212L69.9462 38.8917Z"
+        fill="#05BDBA"></path>
+      <path
+        d="M1.09339 97.5104H75.3711L76.4645 98.6038V109.526L75.3711 110.62H1.09339L0 109.526V98.6038L1.09339 97.5104Z"
+        fill="#05BDBA"></path>
+      <path
+        d="M440.999 97.5104H510.91L512.004 98.6038V109.526L510.91 110.62H436.633L435.539 109.526L439.905 98.6038L440.999 97.5104Z"
+        fill="#05BDBA"></path>
+      <path
+        d="M212.056 108.727L210.963 109.821H177.079L175.986 110.914C175.986 113.101 178.173 119.657 186.916 119.657C190.196 119.657 193.472 118.564 194.566 116.377L195.659 115.284H208.776L209.869 116.377C208.776 122.934 203.313 132.774 186.916 132.774C168.336 132.774 159.589 119.657 159.589 104.357C159.589 89.0576 168.332 75.9408 185.822 75.9408C203.313 75.9408 212.056 89.0576 212.056 104.357V108.731V108.727ZM195.659 97.7971C195.659 96.7037 194.566 89.0538 185.822 89.0538C177.079 89.0538 175.986 96.7037 175.986 97.7971L177.079 98.8905H194.566L195.659 97.7971Z"
+        fill="#014847"></path>
+      <path
+        d="M242.66 115.284C242.66 117.47 243.753 118.564 245.94 118.564H255.776L256.87 119.657V130.587L255.776 131.681H245.94C236.103 131.681 227.36 127.307 227.36 115.284V91.2368L226.266 90.1434H218.617L217.523 89.05V78.1199L218.617 77.0265H226.266L227.36 75.9332V66.0965L228.453 65.0031H241.57L242.663 66.0965V75.9332L243.757 77.0265H255.78L256.874 78.1199V89.05L255.78 90.1434H243.757L242.663 91.2368V115.284H242.66Z"
+        fill="#014847"></path>
+      <path
+        d="M283.1 131.681H269.983L268.889 130.587V56.2636L269.983 55.1702H283.1L284.193 56.2636V130.587L283.1 131.681Z"
+        fill="#014847"></path>
+      <path
+        d="M312.61 68.2871H299.493L298.399 67.1937V56.2636L299.493 55.1702H312.61L313.703 56.2636V67.1937L312.61 68.2871ZM312.61 131.681H299.493L298.399 130.587V78.1237L299.493 77.0304H312.61L313.703 78.1237V130.587L312.61 131.681Z"
+        fill="#014847"></path>
+      <path
+        d="M363.98 56.2636V67.1937L362.886 68.2871H353.05C350.863 68.2871 349.769 69.3805 349.769 71.5672V75.9408L350.863 77.0342H361.793L362.886 78.1276V89.0576L361.793 90.151H350.863L349.769 91.2444V130.591L348.676 131.684H335.559L334.466 130.591V91.2444L333.372 90.151H325.723L324.629 89.0576V78.1276L325.723 77.0342H333.372L334.466 75.9408V71.5672C334.466 59.5438 343.209 55.1702 353.046 55.1702H362.882L363.976 56.2636H363.98Z"
+        fill="#014847"></path>
+      <path
+        d="M404.42 132.774C400.046 143.704 395.677 150.261 380.373 150.261H374.906L373.813 149.167V138.237L374.906 137.144H380.373C385.836 137.144 386.929 136.05 388.023 132.77V131.677L370.536 89.05V78.1199L371.63 77.0265H381.466L382.56 78.1199L395.677 115.284H396.77L409.887 78.1199L410.98 77.0265H420.817L421.91 78.1199V89.05L404.424 132.77L404.42 132.774Z"
+        fill="#014847"></path>
+      <path
+        d="M135.454 131.681L134.361 130.587L134.368 98.9172C134.368 93.4541 132.22 89.2182 125.625 89.0806C122.234 88.9926 118.354 89.0729 114.209 89.2488L113.59 89.8834L113.598 130.587L112.504 131.681H99.3913L98.2979 130.587V77.5388L99.3913 76.4454L128.901 76.1778C143.685 76.1778 149.668 86.3356 149.668 97.8009V130.587L148.575 131.681H135.454Z"
+        fill="#014847"></path>
+    </g>
+    <defs>
+      <clipPath id="clip0_235_8">
+        <rect width="512" height="208.126" fill="white"></rect>
+      </clipPath>
+    </defs>
+  </svg>
+  <slot />
+</article>
+
+<style>
+  article {
+    max-width: 40rem;
+    margin-inline: auto;
+    padding-block: 5rem;
+    flex-direction: column;
+    align-items: center;
+    text-align: center;
+    gap: 0.5rem;
+  }
+  article > :global(*) {
+    max-width: 50ch;
+    margin-top: 0 !important;
+  }
+  small {
+    color: var(--sl-color-gray-3);
+  }
+  svg {
+    width: 15rem;
+  }
+</style>

src/content/docs/about.mdx

@@ -20,8 +20,9 @@ The Open Podcast API project abides by the [Contributor Covenant Code of Conduct
 ## Licensing
 
 Our project builds on and is itself open source:
-* Documentation: Creative Commons Attribution-ShareAlike 4.0 International Public License
-* Reference implementations: MIT
+
+- Documentation: Creative Commons Attribution-ShareAlike 4.0 International Public License
+- Reference implementations: MIT
 
 ### Specifications
 

src/content/docs/index.mdx

@@ -26,13 +26,14 @@ The Open Podcast API is an initiative aiming to provide a feature-complete synch
 <CardGrid>
   <Card title="For users" icon="star">
     - Synchronize subscriptions, listening progress, favorites, queues, and more
-    - Support multiple apps and online services
-    - Enable users to easily switch between providers without losing any information
+    - Support multiple apps and online services - Enable users to easily switch
+    between providers without losing any information
   </Card>
   <Card title="For developers" icon="laptop">
-    - Write clear and comprehensive documentation for features and behaviors
-    - Create reliable specifications that are decentralization-ready and easy to implement
-    - Provide a full [OpenAPI](https://spec.openapis.org/oas/latest) specification
+    - Write clear and comprehensive documentation for features and behaviors -
+    Create reliable specifications that are decentralization-ready and easy to
+    implement - Provide a full [OpenAPI](https://spec.openapis.org/oas/latest)
+    specification
   </Card>
 </CardGrid>
 
@@ -43,9 +44,18 @@ The Open Podcast API initiative builds on open source and open standards. Contri
 We invite all projects and individuals to join us in developing these specifications. This ensures that we take all perspectives into account and create a set of interoperable specs.
 
 <CardGrid>
-  <LinkCard title="Join the chatroom on Matrix" href="https://matrix.to/#/!ZHdcrdWSgxXRREuJdU:matrix.org" />
-  <LinkCard title="Give input in our GitHub discussions" href="https://github.com/orgs/OpenPodcastAPI/discussions/categories/problem-definitions-solutions" />
-  <LinkCard title="Add our monthly meeting to your calendar" href="https://github.com/orgs/OpenPodcastAPI/discussions/15" />
+  <LinkCard
+    title="Join the chatroom on Matrix"
+    href="https://matrix.to/#/!ZHdcrdWSgxXRREuJdU:matrix.org"
+  />
+  <LinkCard
+    title="Give input in our GitHub discussions"
+    href="https://github.com/orgs/OpenPodcastAPI/discussions/categories/problem-definitions-solutions"
+  />
+  <LinkCard
+    title="Add our monthly meeting to your calendar"
+    href="https://github.com/orgs/OpenPodcastAPI/discussions/15"
+  />
 </CardGrid>
 
 <SponsorCallout

src/content/docs/specs/subscriptions/add-new.mdx

@@ -3,6 +3,9 @@ title: Add a new subscription
 description: Add a new subscription
 sidebar:
   order: 2
+badge:
+  text: POST
+  variant: caution
 ---
 
 import CoreAction from "@partials/_core-action.mdx";

src/content/docs/specs/subscriptions/delete.mdx

@@ -3,6 +3,9 @@ title: Delete a subscription
 description: Fetch the status of a deletion process
 sidebar:
   order: 6
+  badge:
+    text: DELETE
+    variant: danger
 ---
 
 import CoreAction from "@partials/_core-action.mdx";

src/content/docs/specs/subscriptions/get-all.mdx

@@ -3,6 +3,9 @@ title: Get all subscriptions
 description: Get all subscriptions for a user
 sidebar:
   order: 3
+  badge:
+    text: GET
+    variant: success
 ---
 
 import CoreAction from "@partials/_core-action.mdx";

src/content/docs/specs/subscriptions/get-single.mdx

@@ -3,6 +3,9 @@ title: Get a single subscription
 description: Get a single subscription for a user
 sidebar:
   order: 4
+  badge:
+    text: GET
+    variant: success
 ---
 
 import CoreAction from "@partials/_core-action.mdx";

src/content/docs/specs/subscriptions/status.mdx

@@ -3,6 +3,9 @@ title: Deletion status endpoint
 description: Fetch the status of a deletion process
 sidebar:
   order: 7
+  badge:
+    text: GET
+    variant: success
 ---
 
 import CoreAction from "@partials/_core-action.mdx";

src/content/docs/specs/subscriptions/update.mdx

@@ -3,6 +3,9 @@ title: Update a subscription
 description: Update details about a subscription
 sidebar:
   order: 5
+  badge:
+    text: PATCH
+    variant: tip
 ---
 
 import CoreAction from "@partials/_core-action.mdx";