openpodcastapi / api-specs Goto Github PK

Following discussions in the Discussions forum, the specification for the subscriptions endpoint needs to be written up to include the following:

1. The issues and scenarios addressed
2. The client <-> server workflow
3. The GUID fetching logic
4. The different endpoint behaviors
5. The expected client behavior
6. The server-side data structure

It would be nice to be able to deploy changes made in a PR to a preview environment so that contributors can see the rendered output when reviewing a PR. Some actions such as PR Preview Action exist to help with this already, so we might be able to use something like the following:

# .github/workflows/preview.yml
name: Deploy PR previews

on:
  # Runs on pull requests targeting the default branch
  pull_request:
    types:
      - opened
      - reopened
      - synchronize

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

concurrency:
  group: preview-${{ github.ref }}
  cancel-in-progress: false

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy-preview:
    runs-on: ubuntu-20.04
    steps:
      # Checkout the branch
      - name: Checkout
        uses: actions/checkout@v3
      # Setup Poetry for dependencies
      - name: Setup Poetry
        uses: Gr1N/setup-poetry@v8
      # Build the site with Poetry
      - name: Build html
        run: |
          cd docs
          poetry install
          poetry run make html
      # Deploy the preview to a subsite
      - name: Deploy preview
        uses: rossjrw/pr-preview-action@v1
        with:
          source-dir: _build/html
          preview-branch: main
          umbrella-dir: docs
          action: auto

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• fix(deps): update dependency sharp to ^0.33.4
• fix(deps): update dependency starlight-openapi to ^0.6.4
• fix(deps): update astro (@astrojs/starlight, astro)
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

• Check this box to trigger a request for Renovate to run again on this repository

The capitalisation comes from RFC2119, which defined some keywords practical for specification designing. E.g. SHOULD is defined as:

This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

So the capitalisation indicates that this definition is used.

If we decide to use this, we have to put the following text somewhere prominent in the spec:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

Originally posted by @JonOfUs in #42 (comment)

https://podcastindex-org.github.io/docs-api/#get-/value/bypodcastguid

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Location: renovate.json
Error type: The renovate configuration file contains some invalid settings
Message: Invalid regExp for packageRules[1].matchPackagePatterns: *astro*

Our OpenAPI Specs show that there might be a 404 on GET /subscriptions, however I am wondering what this means. In which scenario would this happen?

As far as I can tell, the returned json is a list, so in case there is no subscription, it would basically return []. The endpoint is also required, so its not allowed to be missing.

cc @Sporiff

We need to add a sidebar footer linking out to Netlify and to our Code of Conduct in order to get the free Netlify hosting.

We can override the sidebar using the built-in Overrides function. We can largely copy the existing sidebar and build on it.

To host the new documentation site, we need to configure a Sphinx build process and set up deployment to GitHub pages. Once this is configured, we can use a custom domain to access the site.

I think we should improve the docs Makefile:

• Add a hint that the available commands are run in docker
• Provide a build command to build something we can release

@Sporiff Can you help with the second point?

Use https://github.com/rapi-doc/RapiDoc to get something pretty like the Podcast Index API specs (code)

We need to have a site dedicated to hosting our specs and outlining our technical materials. The best documentation platform for this kind of work is Sphinx.

We need to set this up with the following:

• Mermaid for diagramming
• MyST for markdown support
• A responsive and pleasant theme