Add new GUID endpoints (#109)

* Clarify the only support bytag is the value tag https://podcastindex.social/@hypercatcher/110800498311457973 * Add support for getting feed value data from guid https://podcastindex.social/@dave/110851275127076366 * Add support for getting episode value data from feed and episode guid https://podcastindex.social/@dave/110879169344223126 * Remove security for value endpoints * Add support for batch value endpoint https://podcastindex.social/@dave/110895277939377191 * Update version to 1.11.0 * Update to redocly cli 1.0.2 * Change server to use node http-server instead of python * Fix file case issue
Podcastindex-org · Aug 28, 2023 · 4d04a1d · 4d04a1d
1 parent f5c07ce
commit 4d04a1d
Show file tree

Hide file tree

Showing 278 changed files with 11,907 additions and 9,782 deletions.
diff --git a/.redocly.yaml b/.redocly.yaml
@@ -1,24 +1,26 @@
 # See https://redoc.ly/docs/cli/configuration/ for more information.
-apiDefinitions:
-  main: ./api_src/root.yaml
-lint:
-  extends:
-    - recommended
-  rules:
-    no-unused-components: warning
-referenceDocs:
-  htmlTemplate: ./docs/template.html
-  hideDownloadButton: true
-  expandDefaultServerVariables : all # nice for debugging
-  expandResponses: all # nice for debugging
-  expandSingleSchemaField: all # nice for debugging
-  jsonSampleExpandLevel: all # nice for debugging
-  hideSchemaTitles: true
-  requiredPropsFirst: true
-  theme:
-    spacing:
-      sectionVertical: 10
-    colors:
-      primary:
-        main: "#e90000"
-# Additional configuration options: https://github.com/Redocly/redoc
+extends:
+  - recommended
+
+apis:
+  core@v2:
+    root: ./api_src/root.yaml
+    rules:
+      no-unused-components: warn
+
+theme:
+  openapi:
+    htmlTemplate: ./docs/template.html
+    hideDownloadButton: true
+    expandDefaultServerVariables : true # nice for debugging
+    expandResponses: all # nice for debugging
+    expandSingleSchemaField: true # nice for debugging
+    jsonSampleExpandLevel: all # nice for debugging
+    hideSchemaTitles: true
+    requiredPropsFirst: true
+    theme:
+      spacing:
+        sectionVertical: 10
+      colors:
+        primary:
+          main: "#e90000"
diff --git a/Postman Docs/PodcastIndex.postman_collection.json b/Postman Docs/PodcastIndex.postman_collection.json
@@ -418,7 +418,7 @@
 								}
 							]
 						},
-						"description": "This call returns all feeds that support the specified\n[podcast namespace](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md) tag.\n\n\nWhen called without a `start_at` value, the top 500 feeds sorted by popularity are returned in descending order.\n\n\nWhen called with a `start_at` value, the feeds are returned sorted by the `feedId` starting with the specified value\nup to the max number of feeds to return. The `nextStartAt` specifies the value to pass to the next `start_at`.\nRepeat this sequence until no items are returned.\n\n\nExamples:\n  - https://api.podcastindex.org/api/1.0/podcasts/bytag?podcast-value&max=200&pretty\n  - https://api.podcastindex.org/api/1.0/podcasts/bytag?podcast-value&max=200&start_at=1&pretty"
+						"description": "This call returns all feeds that support the specified\n[podcast namespace](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md) tag.\n\nThe only supported tag is `podcast:value` using the `podcast-value` parameter.\n\nWhen called without a `start_at` value, the top 500 feeds sorted by popularity are returned in descending order.\n\n\nWhen called with a `start_at` value, the feeds are returned sorted by the `feedId` starting with the specified value\nup to the max number of feeds to return. The `nextStartAt` specifies the value to pass to the next `start_at`.\nRepeat this sequence until no items are returned.\n\n\nExamples:\n  - https://api.podcastindex.org/api/1.0/podcasts/bytag?podcast-value&max=200&pretty\n  - https://api.podcastindex.org/api/1.0/podcasts/bytag?podcast-value&max=200&start_at=1&pretty"
 					},
 					"response": []
 				},
@@ -1246,7 +1246,7 @@
 								}
 							]
 						},
-						"description": "This call returns the information for supporting the podcast via one of the \"Value for Value\" methods from the PodcastIndex ID.\nAdditionally, the value block data can be accessed using static JSON files (updated every 15 minutes).\n  - Feeds: https://tracking.podcastindex.org/feedValueBlocks.json\n  - Episodes: https://tracking.podcastindex.org/episodeValueBlocks.json\n\nExamples:\n\n  - https://api.podcastindex.org/api/1.0/value/byfeedid?id=920666&pretty\n  - https://api.podcastindex.org/api/1.0/value/byfeedid?id=779873&pretty\n"
+						"description": "This call returns the information for supporting the podcast via one of the \"Value for Value\" methods from the PodcastIndex ID.\nAdditionally, the value block data can be accessed using static JSON files (updated every 15 minutes).\n  - Feeds: https://tracking.podcastindex.org/feedValueBlocks.json\n  - Episodes: https://tracking.podcastindex.org/episodeValueBlocks.json\n\nNote: No API key needed for this endpoint.\n\nExamples:\n\n  - https://api.podcastindex.org/api/1.0/value/byfeedid?id=920666&pretty\n  - https://api.podcastindex.org/api/1.0/value/byfeedid?id=779873&pretty\n"
 					},
 					"response": []
 				},
@@ -1278,7 +1278,113 @@
 								}
 							]
 						},
-						"description": "This call returns the information for supporting the podcast via one of the \"Value for Value\" methods from feed URL.\n\nAdditionally, the value block data can be accessed using static JSON files (updated every 15 minutes).\n  - Feeds: https://tracking.podcastindex.org/feedValueBlocks.json\n  - Episodes: https://tracking.podcastindex.org/episodeValueBlocks.json\n\nExamples:\n\n  - https://api.podcastindex.org/api/1.0/value/byfeedurl?url=https://mp3s.nashownotes.com/pc20rss.xml&pretty\n  - https://api.podcastindex.org/api/1.0/value/byfeedurl?url=https://lespoesiesdheloise.fr/@heloise/feed.xml&pretty\n"
+						"description": "This call returns the information for supporting the podcast via one of the \"Value for Value\" methods from feed URL.\n\nAdditionally, the value block data can be accessed using static JSON files (updated every 15 minutes).\n  - Feeds: https://tracking.podcastindex.org/feedValueBlocks.json\n  - Episodes: https://tracking.podcastindex.org/episodeValueBlocks.json\n\nNote: No API key needed for this endpoint.\n\nExamples:\n\n  - https://api.podcastindex.org/api/1.0/value/byfeedurl?url=https://mp3s.nashownotes.com/pc20rss.xml&pretty\n  - https://api.podcastindex.org/api/1.0/value/byfeedurl?url=https://lespoesiesdheloise.fr/@heloise/feed.xml&pretty\n"
+					},
+					"response": []
+				},
+				{
+					"name": "By Feed GUID",
+					"request": {
+						"method": "GET",
+						"header": [],
+						"url": {
+							"raw": "{{baseUrl}}/value/bypodcastguid?guid=917393e3-1b1e-5cef-ace4-edaa54e1f810",
+							"host": [
+								"{{baseUrl}}"
+							],
+							"path": [
+								"value",
+								"bypodcastguid"
+							],
+							"query": [
+								{
+									"key": "guid",
+									"value": "917393e3-1b1e-5cef-ace4-edaa54e1f810",
+									"description": "(Required) The GUID from the `podcast:guid` tag in the feed. This value is a unique, global identifier for the podcast.\n\nSee the namespace spec for\n[guid](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#guid) for details.\n"
+								},
+								{
+									"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": "This call returns the information for supporting the podcast via one of the \"Value for Value\" methods from podcast GUID.\n\nNote: No API key needed for this endpoint.\n\nExample: https://api.podcastindex.org/api/1.0/value/bypodcastguid?guid=917393e3-1b1e-5cef-ace4-edaa54e1f810&pretty\n"
+					},
+					"response": []
+				},
+				{
+					"name": "By Episode GUID",
+					"request": {
+						"method": "GET",
+						"header": [],
+						"url": {
+							"raw": "{{baseUrl}}/value/byepisodeguid?podcastguid=917393e3-1b1e-5cef-ace4-edaa54e1f810&episodeguid=PC20143",
+							"host": [
+								"{{baseUrl}}"
+							],
+							"path": [
+								"value",
+								"byepisodeguid"
+							],
+							"query": [
+								{
+									"key": "podcastguid",
+									"value": "917393e3-1b1e-5cef-ace4-edaa54e1f810",
+									"description": "(Required) The GUID from the `podcast:guid` tag in the feed. This value is a unique, global identifier for the podcast.\n\nSee the namespace spec for\n[guid](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#guid) for details."
+								},
+								{
+									"key": "episodeguid",
+									"value": "PC20143",
+									"description": "(Required) The guid specified by the `<guid>` in the episode `<item>`."
+								},
+								{
+									"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": "This call returns the information for supporting the podcast episode via one of the \"Value for Value\" methods from\npodcast GUID and the episode GUID.\n\nThe `podcastguid` is the GUID from the `podcast:guid` tag in the feed. This value is a unique, global identifier\nfor the podcast. See the namespace spec for\n[guid](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#guid) for details.\n\nThe `episodeguid` is the unique guid specified for the `<item>` in the feed but may not be globally unique.\n\nNote: No API key needed for this endpoint.\n\nExamples:\n  - https://api.podcastindex.org/api/1.0/value/byepisodeguid?podcastguid=917393e3-1b1e-5cef-ace4-edaa54e1f810&episodeguid=PC20143&pretty\n  - https://api.podcastindex.org/api/1.0/value/byepisodeguid?podcastguid=c73b1a23-1c28-5edb-94c3-10d1745d0877&episodeguid=bdea6759-a7b6-4c0d-9d1e-acca3133f4a9&pretty\n"
+					},
+					"response": []
+				},
+				{
+					"name": "Batch By Episode GUID",
+					"request": {
+						"method": "POST",
+						"header": [],
+						"body": {
+							"mode": "raw",
+							"raw": "{\r\n    \"917393e3-1b1e-5cef-ace4-edaa54e1f810\": [\r\n        \"PC20141\",\r\n        \"PC20142\",\r\n        \"PC20143\"\r\n    ],\r\n    \"c73b1a23-1c28-5edb-94c3-10d1745d0877\": [\r\n        \"bdea6759-a7b6-4c0d-9d1e-acca3133f4a9\"\r\n    ]\r\n}",
+							"options": {
+								"raw": {
+									"language": "json"
+								}
+							}
+						},
+						"url": {
+							"raw": "{{baseUrl}}/value/batch/byepisodeguid",
+							"host": [
+								"{{baseUrl}}"
+							],
+							"path": [
+								"value",
+								"batch",
+								"byepisodeguid"
+							],
+							"query": [
+								{
+									"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": "This call returns the information for supporting the podcast episode via one of the \"Value for Value\" methods from\na JSON object containing one or more podcast GUID and one or more episode GUID for the podcast.\n\nThe JSON object key shall be the `podcastguid` from the `podcast:guid` tag in the feed.\nThis value is a unique, global identifier for the podcast. See the namespace spec for\n[guid](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#guid) for details.\n\nThe value of the `podcastguid` shall be an array of `episodeguid` values.\nThis is the unique guid specified for the `<item>` in the feed but may not be globally unique.\n\nNote: No API key needed for this endpoint."
 					},
 					"response": []
 				}
@@ -1386,7 +1492,7 @@
 								}
 							]
 						},
-						"description": "Notify the index that a feed has changed\n\nExamples:\n\n  - https://api.podcastindex.org/api/1.0/hub/pubnotify?id=920666&pretty\n  - https://api.podcastindex.org/api/1.0/hub/pubnotify?id=920666&update&pretty\n"
+						"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": []
 				}

diff --git a/README.md b/README.md
@@ -4,11 +4,11 @@ See the live docs at https://podcastindex-org.github.io/docs-api/
 
 # Introduction
 
-This project contains the files for describing the PodcastIndex.org API using the 
+This project contains the files for describing the PodcastIndex.org API using the
 [openapi](https://www.openapis.org/) syntax.
 
-The `redocly/openapi-cli` Node package is used to compile the separate files in to a single master file. 
-This master file can be used in many [tools](https://openapi.tools/).  
+The `redocly/cli` Node package is used to compile the separate files in to a single master file.
+This master file can be used in many [tools](https://openapi.tools/).
 
 The [RapiDoc](https://mrin9.github.io/RapiDoc/) software is used to generate the document webpage.
 
@@ -24,7 +24,7 @@ In the project directory, you can run:
 
 ## `yarn preview`
 
-Starts the redoc preview server. 
+Starts the redoc preview server.
 Open [http://localhost:8080](http://localhost:8080) to view it in the browser.
 
 ## `yarn build`
@@ -35,7 +35,7 @@ Runs `bundle_json`, `bundle_yaml`
 
 Generates the master openapi file `pi_api.json` in the `docs` folder.
 
-The `pi_api.json` and `pi_api.yaml` contain the same content just shown in different formats. 
+The `pi_api.json` and `pi_api.yaml` contain the same content just shown in different formats.
 
 ## `yarn bundle_yaml`
 
@@ -49,25 +49,24 @@ Run the redoc linter on the source yaml files.
 
 ## `yarn reload`
 
-Starts a LiveReload file watcher. 
+Starts a LiveReload file watcher.
 
 Install a compatible [browser extension](http://livereload.com/) and connect it to the livereload instance.
 
-Pages connected to the file watcher will reload 2 seconds after the file changes. The 2 second delay gives the 
+Pages connected to the file watcher will reload 2 seconds after the file changes. The 2 second delay gives the
 openapi preview script time to generate the new api files.
 
 ## `yarn server`
 
-Create a simple server in the `docs` folder to serve the release files. 
-
+Create a simple server in the `docs` folder to serve the release files.
 
 # Folder Structure
 
 ## `api_src`
 
 This folder contains the source yaml files for describing the API. The root file is `root.yaml`.
 
-See the [openapi Specification](https://www.openapis.org/) for details on the format. Additional specification details 
+See the [openapi Specification](https://www.openapis.org/) for details on the format. Additional specification details
 from [Swagger](https://swagger.io/specification/) and
 [OpenAPI GitHub](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/).
 
@@ -84,24 +83,24 @@ See additional suggestions for the structure from redoc in the
 
 ### `components`
 
-In general, a folder exists for each object type in the API yaml document. A block that is used in many files should 
+In general, a folder exists for each object type in the API yaml document. A block that is used in many files should
 have a separate yaml file created and be referenced from the files where it is used.
 
-  - `callbacks` - reusable [Callback Objects](http://spec.openapis.org/oas/v3.1.0#callback-object)
-  - `examples` - reusable [Example Objects](http://spec.openapis.org/oas/v3.1.0#example-object)
-  - `headers` - reusable [Header Objects](http://spec.openapis.org/oas/v3.1.0#header-object)
-  - `links` - reusable [Link Objects](http://spec.openapis.org/oas/v3.1.0#link-object)
-  - `parameters` - reusable [Parameter Objects](http://spec.openapis.org/oas/v3.1.0#parameter-object)
-  - `requestBodies` - reusable [Request Body Objects](http://spec.openapis.org/oas/v3.1.0#request-body-object)
-  - `responses` - reusable [Response Objects](http://spec.openapis.org/oas/v3.1.0#responses-object)
-  - `schemas` - reusable [Schema Objects](http://spec.openapis.org/oas/v3.1.0#schema-object)
-  - `securitySchemes` - reusable [Security Scheme Objects](http://spec.openapis.org/oas/v3.1.0#security-scheme-object)
+- `callbacks` - reusable [Callback Objects](http://spec.openapis.org/oas/v3.1.0#callback-object)
+- `examples` - reusable [Example Objects](http://spec.openapis.org/oas/v3.1.0#example-object)
+- `headers` - reusable [Header Objects](http://spec.openapis.org/oas/v3.1.0#header-object)
+- `links` - reusable [Link Objects](http://spec.openapis.org/oas/v3.1.0#link-object)
+- `parameters` - reusable [Parameter Objects](http://spec.openapis.org/oas/v3.1.0#parameter-object)
+- `requestBodies` - reusable [Request Body Objects](http://spec.openapis.org/oas/v3.1.0#request-body-object)
+- `responses` - reusable [Response Objects](http://spec.openapis.org/oas/v3.1.0#responses-object)
+- `schemas` - reusable [Schema Objects](http://spec.openapis.org/oas/v3.1.0#schema-object)
+- `securitySchemes` - reusable [Security Scheme Objects](http://spec.openapis.org/oas/v3.1.0#security-scheme-object)
 
 ## `docs`
 
 Source directory for site source files. This folder should be deployed to the server.
 
-The master api files and images are in the root directory. 
+The master api files and images are in the root directory.
 The root `index.html` uses the [RapiDoc](https://mrin9.github.io/RapiDoc/) UI.
 
 The `template.html` file is the necessary template file for the [redoc](https://redoc.ly/redoc/) preview generated with

diff --git a/api_src/components/parameters/aponly.yaml b/api_src/components/parameters/aponly.yaml
@@ -1,7 +1,7 @@
 name: aponly
 in: query
 # language=Markdown
-description: >
+description: |
   Only returns feeds with an `itunesId`.
 schema:
   type: boolean

diff --git a/api_src/components/parameters/before.yaml b/api_src/components/parameters/before.yaml
@@ -1,7 +1,7 @@
 name: before
 in: query
 # language=Markdown
-description: >
+description: |
   If you pass a PodcastIndex Episode ID, you will get recent episodes before that ID, allowing you to walk back
   through the episode history sequentially.
 schema:

diff --git a/api_src/components/parameters/cat.yaml b/api_src/components/parameters/cat.yaml
@@ -1,7 +1,7 @@
 name: cat
 in: query
 # language=Markdown
-description: >
+description: |
   Use this argument to specify that you **ONLY** want episodes with these categories in the results.
 
 

diff --git a/api_src/components/parameters/chash.yaml b/api_src/components/parameters/chash.yaml
@@ -1,7 +1,7 @@
 name: chash
 in: query
 # language=Markdown
-description: >
+description: |
   The md5 hash of the following feed items in hex format.
   If known, allows for easier duplicate checking.
 

diff --git a/api_src/components/parameters/clean.yaml b/api_src/components/parameters/clean.yaml
@@ -1,7 +1,7 @@
 name: clean
 in: query
 # language=Markdown
-description: >
+description: |
   If present, only non-explicit feeds will be returned.
   Meaning, feeds where the `itunes:explicit` flag is set to `false`.
 

diff --git a/api_src/components/parameters/desc.yaml b/api_src/components/parameters/desc.yaml
@@ -1,7 +1,7 @@
 name: desc
 in: query
 # language=Markdown
-description: >
+description: |
   If present, display feeds in descending order.
   
   

diff --git a/api_src/components/parameters/enclosure.yaml b/api_src/components/parameters/enclosure.yaml
@@ -1,7 +1,7 @@
 name: enclosure
 in: query
 # language=Markdown
-description: >
+description: |
   The URL for the episode enclosure to get the information for.
 required: false
 schema:

diff --git a/api_src/components/parameters/entity.yaml b/api_src/components/parameters/entity.yaml
@@ -1,7 +1,7 @@
 name: entity
 in: query
 # language=Markdown
-description: >
+description: |
   The iTunes entity type to look in
 required: true
 schema:

diff --git a/api_src/components/parameters/episodeguid.yaml b/api_src/components/parameters/episodeguid.yaml
@@ -0,0 +1,9 @@
+name: episodeguid
+in: query
+# language=Markdown
+description: |
+    The guid specified by the `<guid>` in the episode `<item>`.
+required: true
+schema:
+  type: string
+example: "PC20143"
diff --git a/api_src/components/parameters/excludeString.yaml b/api_src/components/parameters/excludeString.yaml
@@ -1,7 +1,7 @@
 name: excludeString
 in: query
 # language=Markdown
-description: >
+description: |
   Any item containing this string will be discarded from the result set.
 
 

diff --git a/api_src/components/parameters/feedid.yaml b/api_src/components/parameters/feedid.yaml
@@ -1,7 +1,7 @@
 name: feedid
 in: query
 # language=Markdown
-description: >
+description: |
   The PodcastIndex Feed ID
 required: false
 schema:

diff --git a/api_src/components/parameters/feedid_newfeeds.yaml b/api_src/components/parameters/feedid_newfeeds.yaml
@@ -1,7 +1,7 @@
 name: feedid
 in: query
 # language=Markdown
-description: >
+description: |
   The PodcastIndex Feed ID to start from (or go to if `desc` specified).