hpr-frontend.old/API

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

request_available_slots:

In:

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

Out:

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

show_request:

In:

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

Out:

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)

cancel_request:

In:

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

Out:

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).