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

https://podcastindex.social/@dave/110974683492205531
Podcastindex-org · Apr 4, 2024 · 3c79eda · 3c79eda
1 parent e7a230c
commit 3c79eda
Show file tree

Hide file tree

Showing 11 changed files with 1,911 additions and 3,538 deletions.
diff --git a/Postman Docs/PodcastIndex.postman_collection.json b/Postman Docs/PodcastIndex.postman_collection.json
@@ -1484,6 +1484,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": {
@@ -1514,6 +1567,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": "",
@@ -1807,6 +1866,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
@@ -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
@@ -1522,6 +1522,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": [
@@ -1538,6 +1583,9 @@
           {
             "$ref": "#/components/parameters/url_pubnotify"
           },
+          {
+            "$ref": "#/components/parameters/reason_liveonly"
+          },
           {
             "$ref": "#/components/parameters/pretty"
           }
@@ -2284,6 +2332,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",

diff --git a/docs/pi_api.yaml b/docs/pi_api.yaml
@@ -1395,6 +1395,40 @@ paths:
           $ref: '#/components/responses/400'
         '401':
           $ref: '#/components/responses/401'
+  /pubnotify:
+    get:
+      tags:
+        - Hub
+      summary: Pub Notify (Hub)
+      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: []
+      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:
@@ -1416,6 +1450,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/id_feed_podcast_pi_pubnotify'
         - $ref: '#/components/parameters/url_pubnotify'
+        - $ref: '#/components/parameters/reason_liveonly'
         - $ref: '#/components/parameters/pretty'
       responses:
         '200':
@@ -2172,6 +2207,47 @@ components:
       schema:
         type: string
       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.
+
+
+        To just send an `update` podping, the `podping` parameter can be used instead.
+      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.
+
+
+        Parameter shall not have a value
+      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.
+
+
+        To just send an `update` podping, use the [https://hub.podcastindex.org/pubnotify](#get-/pubnotify) server instead.
+      schema:
+        type: string
+        enum:
+          - ''
+          - live
+          - liveEnd
+      example: ''
     chash:
       name: chash
       in: query

diff --git a/package.json b/package.json
@@ -18,5 +18,6 @@
     "local": "run-p -cln 'local:*'",
     "local:reload": "livereload . -w 2000 -d -e html,css,js,png,gif,jpg,php,php5,py,rb,erb,coffee,yaml,json",
     "local:server": "http-server docs -c 1 -p 8000"
-  }
+  },
+  "packageManager": "[email protected]"
 }