This API is still under active development as in in version 0 (dev), so endpoints may change without any prior notice. Please use at your own risk.

AUTHENTICATION

Authentication is a two-step process:

1. Request a valid JSON Web Token from the API
2. Sign any escalated command you process through the API with the Token provided

Tokens are in JSON Web Tokens (JWT) format. They are securely signed.

POST: /v0/auth

Use this endpoint to request a token, it requires your application's API Key and API Secret.

• POST: key - Your unique API key
• POST: secret - Your unique API secret

NEVER Give out your API secret to anyone or expose it in any public code.

If successful, you will get a response containing your JWT:

{"jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE0NzgwNDA4NTEsImp0aSI6IklodlljeHhRZWY3cjB5MCtQWTM3b1hYZjd6d0RXTlVjTDFUblA1Y0dJRVE9IiwiaXNzIjoid2lraS5uZXJ2ZW1lZGlhLm9yZy51ayIsIm5iZiI6MTQ3ODA0MDg1MSwiZXhwIjoxNDc4MDQxNzUxLCJkYXRhIjp7InVzZXJJZCI6MSwia2V5IjoiYWJjZCJ9fQ.0F7LmoMYtYk3cuhDuinyZrq5x4Ztd9ivx6qMmTqGZ8g"}

Using the token

When you need to use the token (for actions in the documentation marked as ELEVATED), it needs to be posted in the following format:

Within the HTTP Header of your elevated request, add the following header line:

Authorization: Bearer YOUR_JWT_TOKEN Replacing YOUR_JWT_TOKEN with your token.

ENDPOINTS

Shows

• GET: id - Unique show identifier
• GET: name - Show name (also referred to as the show title)
• GET: description - Show description, this contains a brief overview of the show and its contents
• GET: image - URL to the image to accompany the show

GET: /v0/shows

Returns the full list of shows that exist. This includes any shows that are not assigned to a timeslot.

Example (first 3 results only):

[
   {
        "id": 1,
        "name": "Non-stop Nerve",
        "description": "Non-stop tunes overnight until we're back again tomorrow morning.",
        "image": ""
    },
    {
        "id": 2,
        "name": "Nerve Breakfast Show with Dom, Jack & Andy",
        "description": "Dom, Jack, and Andy wake you up in hilarious fashion as always! ",
        "image": ""
    },
    {
        "id": 4,
        "name": "Hannah Butters & Emma Baker ",
        "description": "Hannah and Emma kick start your midweek mornings! ",
        "image": ""
    }
]

NOTE: For speed, timeslots are not included in any bulk displaying of show information.

GET: /v0/shows/{id}

Returns an individual show, along with any timeslot information which is currently associated with the show.

Example:

{
    "id": 92,
    "name": "Ned Flaherty",
    "description": "Bringing you the best electronic and dance music to start your Friday night!",
    "image": "static.nervemedia.org.uk\/show_images\/56e85b4f1182a.jpg",
    "timeslots": [
        {
            "id": 113,
            "week": 1,
            "day": {
                "int": 1,
                "name": "Monday"
            },
            "start_time": "11:00:00",
            "end_time": "11:59:59",
            "show_id": 92
        },
        {
            "id": 175,
            "week": 1,
            "day": {
                "int": 5,
                "name": "Friday"
            },
            "start_time": "18:00:00",
            "end_time": "18:59:59",
            "show_id": 92
        },
        {
            "id": 347,
            "week": 1,
            "day": {
                "int": 2,
                "name": "Tuesday"
            },
            "start_time": "20:00:00",
            "end_time": "21:59:59",
            "show_id": 92
        }
    ]
}

Timeslots

• GET: id - Unique timeslot identifier
• GET: week - The week that the timeslot resides in. Timetabling works on a two weeks basis, so this is either 1 or 2
• GET: day - The day that the timeslot resides in. Contains an integer (1 = Monday, 7 = Sunday) and a friendly name
• GET: start_time - The time that the timeslot starts
• GET: end_time - The time that the timeslots ends
• GET: show_id - The ID of the show (if any) that resides inside the timeslot

Played History

• GET: created - When the history item was stored/created. It can be assumed that this is also the start time of the item

• GET: type - Currently contains either a "track" object, or an "other" string. Other meaning not a song/track that should be identified (such as a bed or jingle)

• Track object:

  • GET/POST: artist (required) - Artist of the track
  • GET/POST: title (required) - Title of the track being played
• Other object:
  • POST: n/a (no POST parameters required)

GET: /v0/played_history

Returns the history of played items, in descending time order.

POST: /v0/played_history/track

Add a new track to the played history, the timestamp is currently assumed to be instant (so the track you are adding has just started playing).

Data to include in the PUT is above, under the "Track object" bulletpoint. Example POST:

{
  "title": "Sorry",
  "artist": "Justin Bieber"
}

Example response:

{
  "success": "POST Action was successful",
  "http_code": "200"
}

POST: /v0/played_history/other

Add a non-track item to the played history, the timestamp is currently assumed to be instant (so the item you are adding has just started playing).

No body data is required for this POST, as there is currently no information stored about items that are not tracks.

Example response:

{
  "success": "POST Action was successful",
  "http_code": "200"
}