Planning out an API

It has been established in several threads, that a stable API for developing plugins and integrations against would be helpful. See here and here.

This thread is intended as a place to iron out what the most useful features of an API would be so that it is clearer when it comes to implementing what should be prioritised. After we have a rough consensus here, I will file GitHub issues with a more robust spec.

Please let me know your thoughts

What I am missing most about the API ist a well structured documentation for an API surface that allows integrating external systems (ie. a wordpress instance, drupal, an archival system).

At RaBe we had the requirement that our broadcast log/archival solution needed to access a listing of shows. Our developer on that project ended up directly accessing the LibreTime database. I guess a stable API surface that helps access info on the program grid/schedule could help out there.

On the web side we would also like to consume the program grid from LibreTime. Give that we would like to use readily available CMS solutions without needing to do too much integration work I’ve been experimenting with CalDAV. Some time ago I wrote some proof-of-concept code that extracts LibreTime data, transforms it to CalDAV and then loads it into a CalDAV server. At the time CalDAV seemed like a nice fit for exposing program grid data. If this still holds true it might be interesting to consider exposing some of what is possible on the schedule page through CalDAV. At my station we sure have quite some use-cases that could be covered by CalDAV alone.

Since CalDAV offers a rather constrained API I’m sure that some more API, maybe RESTful, make sense as well. I recently did some hard staring at what is already available in that space.

I guess the parts that most resemble a somewhat sane RESTful API live in the airtime_mvc/application/modules/rest/controllers directory.
Some of the controllers in there are only partially implemented though and it looks like the MediaController is the only one that sees much use due to it being used by analyzer, celery and pypo.

While I know that it’s possible to build nice APIs using ZF1. It might also be that building out a proper, documented API surface could be a perfect fit for a small MicroService run in tandem to the ZF1 app. Maybe a small flask thing (or even something based on django-rest-framework) that uses our current database to render a modern API.

Anywhoo… Before I get carried away too much. I guess my answer to the original question would be that we need a well structured, discoverable, documented (most likely RESTful) API surface. There is also potential for some added value if we consider implementing some domain specific APIs (like CalDAV).

We might also look around at other related standards. Things like EbuCore might help name and structure stuff in a way that we could assume other broadcast solutions could understand. White EbuCore is a metadata standard rather than an API standard we could consider exposing metadata inspired by stuff from there.

1 Like

I like the idea of exporting the program grid as CalDAV. That would be useful both plain (for scheduling) and integrated into plugins (now/next, etc). I agree that we would need something more too though.

Hmm… The micro-service approach would be nice, that way we do not bind ourselves deeper to the ZF1 framework and could (maybe) eventually replace the current front-end with one that is completely decoupled and interacts only with the API.

A common naming and structure would be very useful. EbuCore looks promising from the short skim-through I did.

Assuming an API would be separate project from the 3.0 release (https://github.com/LibreTime/libretime/projects/2)?

Once the scope is defined, we might want to consider creating a campaign on the LibreTime collective (https://opencollective.com/libretime) to help achieve this goal.

Yes, it would be nice to have it ready for 3.0, but it isn’t a release blocker

Potentially that could work well

I’ve written some tools for extending LibreTime for our own use, which are at https://gitlab.com/kenrestivo/djdash

OAuth2 API would be nice, as would CalDAV for the calendar.

Not sure if it counts as API or not, but some way to store audio files on a remote file system would be great.

I maintain the Radio Station plugin for WordPress and we are looking to pull the following from LibreTime:

  1. Shows
  2. Show Schedule
  3. DJ (user)
  4. Playlists
  5. Live Stream URL

We would love to read/write though back into LibreTime, so once the show schedule is passed into WordPress on the first connection, the show schedule can be updated in WordPress the push up into LibreTime.

We’d want to create in WordPress new shows that are crated and scheduled in LibreTime, so they publish into WordPress automatically and we’d want to pull the DJ user role into WordPress agains the Show they are related to.

Also, we’d love to find a way to add our podcast fees in WordPress and have the API connect them up to shows created in LibreTime.

Cross-posting this comment from @paddatrapper https://github.com/LibreTime/libretime/issues/935#issuecomment-571930675

If we define a solid API, implement it in some framework and then work on replacing parts of the UI as we the functionality is developed, we probably will have more success. This also ensures that people can upgrade their instances without much risk. This is something I think we could use the OpenCollective for, even if we are only providing a small amount to a developer each month.

From next month I can commit at least about 4 hours a week to this. I would us to plan out an API first before we start implementing anything.

Kyle identified the following major areas of operation that LibreTime needs and asked for additional feedback.

  • Library - this is a list of songs/podcasts/playlists (both smart and not) that forms the base of a show.
  • Item - a file on the disk that has metadata associated with it. This could be a music file, a podcast episode, or an advert source. These are uploaded to the server by users.
  • Podcast - an RSS feed of files that are downloaded regularly to the disk.
  • Playlist - a list of files that will be played sequentially.
  • Smartblock - a set of conditions that match 0 or more items that will create a playlist at some later point.
  • Show - a list of playlists and items that will be played at a specific time. These can be linked together to form repeating shows. A show can be connected to a live source which associates with a user’s credentials.
  • Advert Block - a point in time of one or more shows where 0 or more adverts can play.
  • Advert Campaign - A list of advert sources that collectively have a start and end date and time. It also has an associated schedule of when which adverts should play. These are inserted into the relevant shows.
  • User - an account that can log into the system. There are various permission levels that will grant the user access to different things.
  • Live Source - a source of input that will be connected and streamed to.
  • Destination - a streaming output from the system

Is there anything else the API should provide?

How would the API plugin to something like WordPress? LibreTime plugin?

The following flow @djtonyz describes above and here, could be a great use case for WordPress integration with a new release of Radio Station plugin included in the MVP for stations and podcasters under development.

We’re hoping to finalize and launch a paid beta where we’d be delivering services while developing the MVP. Hopefully, that will provide a way to help fund development of the API and related integrations.

Because there’s a wide-ranging need for this functionality, the chances are good we could also run a successful crowdfunding campaign to make it happen.