Add hub.podcastindex.org endpoint and podping parameters to hubnotify

https://podcastindex.social/@dave/110974683492205531
Podcastindex-org · Sep 18, 2023 · 9199f15 · 9199f15
1 parent b162026
commit 9199f15
Show file tree

Hide file tree

Showing 10 changed files with 306 additions and 4 deletions.
diff --git a/Postman Docs/PodcastIndex.postman_collection.json b/Postman Docs/PodcastIndex.postman_collection.json
@@ -1478,6 +1478,59 @@
 		{
 			"name": "hub",
 			"item": [
+				{
+					"name": "Pub Notify (Hub)",
+					"request": {
+						"auth": {
+							"type": "noauth"
+						},
+						"method": "GET",
+						"header": [],
+						"url": {
+							"raw": "{{baseHubUrl}}/pubnotify",
+							"host": [
+								"{{baseHubUrl}}"
+							],
+							"path": [
+								"pubnotify"
+							],
+							"query": [
+								{
+									"key": "id",
+									"value": "75075",
+									"description": "The PodcastIndex Feed ID\n\nThe `id` or the `url` is required.",
+									"disabled": true
+								},
+								{
+									"key": "url",
+									"value": "https://feeds.theincomparable.com/batmanuniversity",
+									"description": "The Podcast Feed URL\n\nThe `id` or the `url` is required.",
+									"disabled": true
+								},
+								{
+									"key": "reason",
+									"value": "",
+									"description": "Send a [podping](https://github.com/Podcastindex-org/podping-hivewriter#podping-reasons) with the specified reason.\n\nTo just send an `update` podping, the `podping` parameter can be used instead.\n",
+									"disabled": true
+								},
+								{
+									"key": "podping",
+									"value": "",
+									"description": "Send a [podping](https://github.com/Podcastindex-org/podping-hivewriter#podping-reasons) with an `update` reason.\n\nParameter shall not have a value\n",
+									"disabled": true
+								},
+								{
+									"key": "pretty",
+									"value": "",
+									"description": "If present, makes the output “pretty” to help with debugging.\n\nParameter shall not have a value\n",
+									"disabled": true
+								}
+							]
+						},
+						"description": "Notify the index that a feed has changed\n\nNote: No API key needed for this endpoint.\n\nExamples:\n  - https://api.podcastindex.org/api/1.0/hub/pubnotify?id=920666&pretty\n  - https://api.podcastindex.org/api/1.0/hub/pubnotify?url=https://feeds.theincomparable.com/batmanuniversity&pretty\n"
+					},
+					"response": []
+				},
 				{
 					"name": "Pub Notify",
 					"request": {
@@ -1508,6 +1561,12 @@
 									"description": "The Podcast Feed URL\n\nThe `id` or the `url` is required.",
 									"disabled": true
 								},
+								{
+									"key": "reason",
+									"value": "",
+									"description": "Send a [podping](https://github.com/Podcastindex-org/podping-hivewriter#podping-reasons) with the specified reason.\n\nTo just send an `update` podping, use the [https://hub.podcastindex.org/pubnotify](#get-/pubnotify) server instead.\n",
+									"disabled": true
+								},
 								{
 									"key": "pretty",
 									"value": "",
@@ -1801,6 +1860,10 @@
 		{
 			"key": "baseAppleUrl",
 			"value": "https://api.podcastindex.org/"
+		},
+		{
+			"key": "baseHubUrl",
+			"value": "https://hub.podcastindex.org/"
 		}
 	]
 }
diff --git a/api_src/components/parameters/podping.yaml b/api_src/components/parameters/podping.yaml
@@ -0,0 +1,11 @@
+name: podping
+in: query
+# language=Markdown
+description: |
+  Send a [podping](https://github.com/Podcastindex-org/podping-hivewriter#podping-reasons) with an `update` reason.
+
+
+  Parameter shall not have a value
+schema:
+  type: boolean
+allowEmptyValue: true
diff --git a/api_src/components/parameters/reason.yaml b/api_src/components/parameters/reason.yaml
@@ -0,0 +1,15 @@
+name: reason
+in: query
+# language=Markdown
+description: |
+  Send a [podping](https://github.com/Podcastindex-org/podping-hivewriter#podping-reasons) with the specified reason.
+
+
+  To just send an `update` podping, the `podping` parameter can be used instead.
+schema:
+  type: string
+  enum:
+    - ""
+    - "live"
+    - "liveEnd"
+example: ""
diff --git a/api_src/components/parameters/reason_liveonly.yaml b/api_src/components/parameters/reason_liveonly.yaml
@@ -0,0 +1,15 @@
+name: reason
+in: query
+# language=Markdown
+description: |
+  Send a [podping](https://github.com/Podcastindex-org/podping-hivewriter#podping-reasons) with the specified reason.
+
+
+  To just send an `update` podping, use the [https://hub.podcastindex.org/pubnotify](#get-/pubnotify) server instead.
+schema:
+  type: string
+  enum:
+    - ""
+    - "live"
+    - "liveEnd"
+example: ""
diff --git a/api_src/paths/hub/hub.pubnotify.yaml b/api_src/paths/hub/hub.pubnotify.yaml
@@ -0,0 +1,34 @@
+get:
+  tags:
+    - Hub
+  summary: Pub Notify (Hub)
+  # language=Markdown
+  description: |
+    Notify the index that a feed has changed
+
+
+    Note: No API key needed for this endpoint.
+
+
+    Examples:
+
+      - https://hub.podcastindex.org/pubnotify?id=920666&pretty
+      - https://hub.podcastindex.org/pubnotify?url=https://feeds.theincomparable.com/batmanuniversity&pretty
+  operationId: pubnotify
+  security: [] # no security required
+  servers:
+    - url: https://hub.podcastindex.org
+      description: "Server for handling feed publish/update notifications"
+  parameters:
+    - $ref: '../../components/parameters/id_feed_podcast_pi_pubnotify.yaml'
+    - $ref: '../../components/parameters/url_pubnotify.yaml'
+    - $ref: '../../components/parameters/reason.yaml'
+    - $ref: '../../components/parameters/podping.yaml'
+    - $ref: '../../components/parameters/pretty.yaml'
+  responses:
+    '200':
+      $ref: '../../components/responses/hub_pubnotify.yaml'
+    '400':
+      $ref: '../../components/responses/400.yaml'
+    '401':
+      $ref: '../../components/responses/401.yaml'
diff --git a/api_src/paths/hub/pubnotify.yaml b/api_src/paths/hub/pubnotify.yaml
@@ -19,6 +19,7 @@ get:
   parameters:
     - $ref: '../../components/parameters/id_feed_podcast_pi_pubnotify.yaml'
     - $ref: '../../components/parameters/url_pubnotify.yaml'
+    - $ref: '../../components/parameters/reason_liveonly.yaml'
     - $ref: '../../components/parameters/pretty.yaml'
   responses:
     '200':

diff --git a/api_src/root.yaml b/api_src/root.yaml
@@ -1,6 +1,6 @@
 openapi: 3.0.2
 info:
-  version: 1.11.0
+  version: 1.11.1
   title: PodcastIndex.org API
   termsOfService: 'https://github.com/Podcastindex-org/legal/blob/main/TermsOfService.md'
   contact:
@@ -233,6 +233,8 @@ paths:
     $ref: 'paths/stats/current.yaml'
   '/categories/list':
     $ref: 'paths/categories/list.yaml'
+  '/pubnotify':
+    $ref: 'paths/hub/hub.pubnotify.yaml'
   '/hub/pubnotify':
     $ref: 'paths/hub/pubnotify.yaml'
   '/add/byfeedurl':

diff --git a/docs/pi_api.json b/docs/pi_api.json
@@ -1,7 +1,7 @@
 {
   "openapi": "3.0.2",
   "info": {
-    "version": "1.11.0",
+    "version": "1.11.1",
     "title": "PodcastIndex.org API",
     "termsOfService": "https://github.com/Podcastindex-org/legal/blob/main/TermsOfService.md",
     "contact": {
@@ -1519,6 +1519,51 @@
         }
       }
     },
+    "/pubnotify": {
+      "get": {
+        "tags": [
+          "Hub"
+        ],
+        "summary": "Pub Notify (Hub)",
+        "description": "Notify the index that a feed has changed\n\n\nNote: No API key needed for this endpoint.\n\n\nExamples:\n\n  - https://hub.podcastindex.org/pubnotify?id=920666&pretty\n  - https://hub.podcastindex.org/pubnotify?url=https://feeds.theincomparable.com/batmanuniversity&pretty\n",
+        "operationId": "pubnotify",
+        "security": [],
+        "servers": [
+          {
+            "url": "https://hub.podcastindex.org",
+            "description": "Server for handling feed publish/update notifications"
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/id_feed_podcast_pi_pubnotify"
+          },
+          {
+            "$ref": "#/components/parameters/url_pubnotify"
+          },
+          {
+            "$ref": "#/components/parameters/reason"
+          },
+          {
+            "$ref": "#/components/parameters/podping"
+          },
+          {
+            "$ref": "#/components/parameters/pretty"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/hub_pubnotify"
+          },
+          "400": {
+            "$ref": "#/components/responses/400"
+          },
+          "401": {
+            "$ref": "#/components/responses/401"
+          }
+        }
+      }
+    },
     "/hub/pubnotify": {
       "get": {
         "tags": [
@@ -1535,6 +1580,9 @@
           {
             "$ref": "#/components/parameters/url_pubnotify"
           },
+          {
+            "$ref": "#/components/parameters/reason_liveonly"
+          },
           {
             "$ref": "#/components/parameters/pretty"
           }
@@ -2271,6 +2319,43 @@
         },
         "example": "https://feeds.theincomparable.com/batmanuniversity"
       },
+      "reason": {
+        "name": "reason",
+        "in": "query",
+        "description": "Send a [podping](https://github.com/Podcastindex-org/podping-hivewriter#podping-reasons) with the specified reason.\n\n\nTo just send an `update` podping, the `podping` parameter can be used instead.\n",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "",
+            "live",
+            "liveEnd"
+          ]
+        },
+        "example": ""
+      },
+      "podping": {
+        "name": "podping",
+        "in": "query",
+        "description": "Send a [podping](https://github.com/Podcastindex-org/podping-hivewriter#podping-reasons) with an `update` reason.\n\n\nParameter shall not have a value\n",
+        "schema": {
+          "type": "boolean"
+        },
+        "allowEmptyValue": true
+      },
+      "reason_liveonly": {
+        "name": "reason",
+        "in": "query",
+        "description": "Send a [podping](https://github.com/Podcastindex-org/podping-hivewriter#podping-reasons) with the specified reason.\n\n\nTo just send an `update` podping, use the [https://hub.podcastindex.org/pubnotify](#get-/pubnotify) server instead.\n",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "",
+            "live",
+            "liveEnd"
+          ]
+        },
+        "example": ""
+      },
       "chash": {
         "name": "chash",
         "in": "query",