Batching and OPML

Just a couple of new features added this week, but these are potentially useful for integration with other systems.

Batch API

This allows a number of API calls to be submitted at the same time and executed in a single network roundtrip. All of the requested API calls are executed together, and if one of them fails, any changes for the whole batch is rolled-back so there will be no impact.

Documentation for the Batch API is here.

OPML APIs

The standard for import/export for podcast and RSS apps is OPML. Feeddirectory.org now has import and export of OPML files available through an API for subscriptions only. The same level of functionality over the published feeds will be coming soon.

Documentation for the OPML APIs are: here for download and here for upload.

Health checking feeds

It was always the intention with feeddirectory.org to add some value to the URLs that are stored in it. One of these value adds is the ability to report on the health of a feed. This is done by checking each URL that's stored on a regular basis - at most once per day. 

Only very basic checks are performed:

• Get the HTTP response code
• Check the if the XML document is well-formed

This information is then passed back with API calls that return URLs in a feed-health section:

         "feed-health" : {
            "last-status-code" : 200,
            "is-valid-xml" : true,
            "metadata" : {
               "title" : "No Such Thing As A Fish"
            },
            "last-fail-check" : {
               "timestamp" : null,
               "epoch-millis" : null
            },
            "last-good-check" : {
               "timestamp" : "2021-03-03T20:15:18.569+00:00",
               "epoch-millis" : 1614802518569
            },
            "last-checked" : {
               "timestamp" : "2021-03-03T20:15:18.569+00:00",
               "epoch-millis" : 1614802518569
            }
         }

This information will be refreshed regularly. There is no separate API to refresh the health of a URL, they will be refreshed automatically and the updated information returned in subsequent API results.

Permissions, Followers, Comments

Lots of work done since the last post here.  I've had some great feedback from a few application developers that has shaped some of the decisions made. Thanks to everybody that have contributed.

We've now got:

Permissions

Permission levels for accounts, subscriptions, published items, and follows. This allows 3 levels of visibility for each: 

• public
• followers-only
• private

...and each item can have its own permission.

Authorised Followers

You can set your account so that anybody that want to follow you must be authorised. This allows for a closed user group to be built.

Comments

This one I'm quite excited about. Comments can be added against positions in episodes. For podcasts this would allow comments to be made in the context of what's being said at a particular point. The comments can then be "played back" along with the audio. This brings to podcasts the fun (or chaos) of a live chatroom during a live stream. For text based RSS feeds, it allows comments to be added to sections of a document. 

Comments can be voted up or down, and there's the ability to flag comments as abusive or spam.

In addition to plain text, each comment can contain some structured data (JSON). I've no idea how this will be used, but thought it may be useful - go invent if you're building a client.

So, please, check out the new APIs, and let me know if you find any problems or have a suggestion.

Another day, another API

Another great suggestion that's been made is the ability to mark an episode / item as completed to signal that you have listened to, or read an item in an RSS feed. This sort of thing is essential for Podcast players so they can keep track of what has and has not been played already.

So now the Episode/Position/Set API now has an optional parameter of "completed":

https://feeddirectory.org/#/api/1.0/Episode/Position/Set

More APIs relating to episodes / items coming in the next few days.

Episode syncing

An excellent suggestion from James Cridland over on https://podcastindex.social/ was to have the ability to store on the directory the "most recently played position" for each podcast in a feed. This would allow a user to pause playing on one app, and then pick up from the last position on another app.

This was a relatively simple API to add in a generic way so that it can apply to any media type. The position that's stored is just an integer value. For audio/video this could be the number of seconds into the playback. For written words it could be a paragraph number.

So now, the API contains:

/api/1.0/Episode/Position/Set

/api/1.0/Episode/Position/Get

Really look forward to this being supported in podcast players.

We're live, kinda

After a few weeks of designing and coding, redesigning and then refactoring, I've pushed the first version of the feeddirectory.org code live.

Some initial testing has been done and it all looks fine so far, but I'm sure there's some gotchas that'll be found when it starts getting some use.

Comment below if you're experiencing any issues, would like another API adding, or are just interested in what's happening. Alternatively get in touch on podcastindex.social.

I'll get all of the code up on GitHub when I've finished tidying things up, but that's a job for another day.