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.

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.