You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Christoph 598bfe4755 Fixed README GLFM 3 years ago
.. Fixed README GLFM 3 years ago

HPR automation API design

Table of contents

  1. Introduction
  2. Architecture
  3. Requirements
  4. Assumptions / open points
  5. Implementation

(c) Chris Zimmermann 2020 CC-BY-SA

1. Introduction

At the moment if a hosts wants to upload a show, they have to use a manual workflow which consists of selecting a date, registering an upload for this date, filling in a form after an email-based confirmation and then finally uploading the corresponding audio file.

The idea behind this API is the provision of a level of automation which will allow hosts to contribute shows including their meta-information such as shownotes, host data, etc. in an automated fashion thus eliminating media breaks and errors caused by the current manual approach.

2. Architecture

The API will use a REST-based approach for the following reasons:

  • REST is an industry-accepted format which is widely used in the web space and beyond
  • Comprehensive tooling support for a number of popular programming languages and tech stacks
  • Easy debugging as data is transmitted in cleartext before / after HTTPS decryption
  • HTTP(S)-based allowing easy integration in existing firewall / ITSec ecosystems

The following ASCII art depicts the general architecture / workflow:

                                  REST API

+---------+                                               +-------------+
|         |                -- Token (API/Bearer) -->      |             |
|         |    -- Request available slots                 |             | 
|   Host  |                    (<within date range>) -->  |    HPR      |
|         |                 <-- Available slots --        |             |
|         |    -- Show request (including meta data       |             |
|         |                  / audio stream) -->          |             |
+---------+         <-- Acceptance confirmation --        +-------------+

The following provides a draft of the corresponding API (optional parameters in []), all data is expected to be JSON-based



Name(s) Type Remark
token string Bearer / API token
[start_date] string ISO-8601 compliant date
if missing, first avaible slot will be returned
[end_date] string ISO-8601 compliant date
If stated, no slot after date will be chosen


Name(s) Type Remark
slot_available boolean Indicates if slot available
errno integer Indicates error condition*
slot string ISO-8601 compliant date
  • Possible errno values:

    0 No error

    1 Invalid start date

    2 Invalid end date

    3 Invalid token



Name(s) Type Remark
date string ISO-8601 compliant date indicating selected slot
show_name string
summary string
show_notes string HTML snippet containing the show notes
format_notes string Plain text, HTML5, Markdown (pandoc), Markdown (GH), RestructuredText, txt2tags
audio_stream string base64 encoded mp3/ogg/spx data*
audio_url string Download URL for audio stream*
explicit boolean
intro_present boolean audio stream contains intro music
outro_present boolean audio stream contains outro music
tags string comma-separated list of tags
[handle] string if given, use this handle (default: handle associated with authentication token
[license] string CC-BY-* license to be used (default: CC-BY-SA)
[series] string Optional series specifier
[profile] string Optional profile description
* either audio_stream or audio_url must be present


Name(s) Type Remark
id string Confirmation ID (-1 it not accepted)
errno integer If id == -1, errno contains reason for rejection*
errstr string Auxiliary error information, default: emtpy
  • Possible errno values:

    0 No error

    1 Mandatory field missing (errstr contains parameter ID)

    2 Upload problem (includes any decoding issues)

    3 Download problem (audio_url invalid?)

    4 Invalid date

    5 Request validity period expired (similar to curernt workflow, show_request must be issued no later than 15 minutes after request_available_slots returns with a valid date spec)



Name(s) Type Remark
id string Confirmation ID for cancelation request


Name(s) Type Remark
canceled boolean Cancelation confirmation
errno integer Reason indication why cancelation was not possible*
  • Possible errno values:

    0 No error

    1 Cancelation not possible

    2 Cancelation requested issued past airing date

3. Requirements

The choice of the technology stack is Flask + Connexion as this is a tried and tested combination consisting of mature and widely accepted Python 3 components. Given the wide adoption of this stack and especially Python 3 as an implementation language, this approach has the advantage the the code base will be easily maintanable as knowledge around this ecosystem is common among developers.

Needless to say, similar frameworks are available in the PHP and Java worlds if for whatever reason a Python 3-based stack is not favourable as an implementation choice.

For the above stack, we need an open source plattform (ideally a Linux spin) with the following components:

  • Python 3.6+
  • pip3
  • Flask + Connexion
  • Access to the documented backend infrastructure

4. Assumptions / open points:

  • Access to a documented backend / DB for storing the show information.
  • Integration with the overall RSS feed (also for any series hosted on HPR such as Linux Inlaws with separate RSS feeds).
  • Simple registration site / workflow will be required for the initial token configuration / grant
  • As the above API caters for a cancelation of an already submitted episode, it may be wort considering another show_request variant with the semantics of maintaining a waiting list of shows aiming for the next available if a cancelation occurs. IMHO at the moment, the potential implementation complexity far outweigh the benefits of this use case as I assume that such a cancelation of an already confirmed show for a slot very rarely occurs if at all.
  • What else?

5. Implementation

Details of the implementation (TBC).