Skip to content

REST API extension

Is your feature request related to a problem? Please describe

I need to fetch contents from Castopod to other clients, e.g. custom mobile app.

The REST API added in #210 (closed) is nice, but it is relatively simple. Currently displaying e.g. list of the most recent episodes (across all podcasts) requires iterating over multiple endpoints.

Describe the solution you'd like

There should be an endpoint that allows to query episodes, similarly to how we can now query podcasts.

Additional context

The added endpoints would be

  • GET /api/rest/v1/episodes
  • GET /api/rest/v1/episode/{id}

The first endpoint will accept additional optional query parameters, allowing to narrow the search:

  • order - string (newest|search) - search method
    • if set to newest sort from the newest to the oldest,
    • if set to search and there's a search parameter given - sort by search match rating starting from the best match,
    • if not set, act as in newest.
  • count - integer > 0 - amount of records to return
    • if not set, no limit
  • start - integer >= 0, index of the first record returned
    • if not set, 0
  • podcastIds - comma-separated integers - identifiers of podcasts that should be queried
    • if not set, query all podcasts
  • search - string - search phrase
    • if not set, do not limit query by search

In case of search it should do a full text search using any mechanism directly available in MySQL/MariaDB on fields

  • podcast.title
  • podcast.handle
  • podcast.description_markdown
  • episode.title
  • episode.slug
  • episode.description_markdown
  • episode.location_name

Additional context

As in case of #210 (closed) I'm ready to sponsor such development.

Please let me know if the design of the API is OK and whether we can proceed.

Edited by Marcin Lewandowski