diff --git a/Postman Docs/PodcastIndex.postman_collection.json b/Postman Docs/PodcastIndex.postman_collection.json index 7798664..8bc4ba2 100644 --- a/Postman Docs/PodcastIndex.postman_collection.json +++ b/Postman Docs/PodcastIndex.postman_collection.json @@ -1472,6 +1472,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": { @@ -1502,6 +1555,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": "", @@ -1795,6 +1854,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 new file mode 100644 index 0000000..9539a51 --- /dev/null +++ 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 new file mode 100644 index 0000000..b14935c --- /dev/null +++ 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 new file mode 100644 index 0000000..e071803 --- /dev/null +++ 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 new file mode 100644 index 0000000..cea270e --- /dev/null +++ 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 index 870dbbd..85e6b9d 100644 --- 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 index 0479174..abd52aa 100644 --- 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 index 093409e..33371fc 100644 --- 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": { @@ -1516,6 +1516,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": [ @@ -1532,6 +1577,9 @@ { "$ref": "#/components/parameters/url_pubnotify" }, + { + "$ref": "#/components/parameters/reason_liveonly" + }, { "$ref": "#/components/parameters/pretty" } @@ -2259,6 +2307,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 index e72c754..8645a69 100644 --- a/docs/pi_api.yaml +++ b/docs/pi_api.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: @@ -1386,6 +1386,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: @@ -1407,6 +1441,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': @@ -2139,6 +2174,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 index c410c68..2c5aacc 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "pi_api_docs", - "version": "1.11.0", + "version": "1.11.1", "private": true, "devDependencies": { "@redocly/cli": "^1.0.2",