Why a new version of RTDS?

Actually, RTDS allows applications to get all data with only one URL. But, with RTDS2, it seems more legit to create a full REST API system where you will be able to get some data, more precisely like:

  • GET /tags: Gets tags like artists, title, album, …
  • GET /station: Gets information about the currently listened station
  • GET /station/xxx: Gets information about a defined station (named xxx)
  • GET /show: Gets information about the currently streamed show
  • etc.

By the way, with POST requests, you will be able to change data and cache it, and to be sure that no one can change those data, OAuth system will be implemented.

So, it's not anymore just a protocol but it's becaming an application?

Yes! First, I will have to specify everything (protocol, urls, data, …), then I will implement RTDS2 in PHP. When done, everything will be published on Github and you will be free to implement RTDS2 protocol with the defined rules (that will public too).

When will it be public?

I don't know. RTDS2 is not currently my priority. But I hope to work on it soon and publish the version 2 of RTDS late 2018.

Current draft (as of 2018-06-20)

Standard response:

  • status: about status for the request (http code, message)
  • response: object of the response
  • urls: URL that can be called to link data

Data requested by GET methods can come from:

  • Configuration files
  • Custom implemented methods to create a link between RTDS2 and your database
  • Automatically generated contents (tokens, for example)

GET /oauth/autorize?app_id={id.string}&app_secret={secret.string}

{
    "status": status{
        "code": number,
        "message": string
    },
    "response": token{
        "token": string,
        "validity": timestamp
    },
    "urls": {}
}

POST /{station.string}/tags?token={token.string} DATA tags={tags.json}

{
    "status": status{},
    "response": {},
    "urls": {}
}

POST /{station.string}/show?token={token.string} DATA show={show.json}

{
    "status": status{},
    "response": {},
    "urls": {}
}

GET /{station.string}/tags?token={token.string}

{
    "status": status{},
    "response": song{
        "artist": string,
        "title": string,
        "album": string,
        "year": number,
        "genres": [string, …],
        "categories": [string, …],
        "bio": string,
        "cover": image{
            "type": enum(pixel, vector),
            "format": enum(square, free) OR string,
            "url": string,
            "width": number,
            "height": number,
            "transparency": boolean,
            "description": string
        },
        "images": [
            image{},
            …
        ],
        "urls": [
            url{
                "type": enum(web, social, parent, player, listen, legal_notice, contact, buy, stream, extra),
                "url": string,
                "description": string
            }
        ],
        "artists": [
            artist{
                "name": string,
                "bio": string,
                "images": [
                    image{},
                    …
                ],
                "urls": [
                    url{},
                    …
                ]
            }, 
            …
        ],
        "length": number,
        "remaining": number,
        "extra": […]
    },
    "urls": {
        "station": string,
        "show": string,
        "previous": string,
        "next": string
    }
}

GET /{station.string}/previous?token={token.string}

{
    "status": status{},
    "response": song{},
    "urls": {
        "station": string,
        "show": string,
        "current": string,
        "next": string
    }
}

GET /{station.string}/next?token={token.string}

{
    "status": status{},
    "response": song{},
    "urls": {
        "station": string,
        "show": string,
        "previous": string,
        "current": string
    }
}

GET /stations?token={token.string}

{
    "status": status{},
    "response": stations{
        "stations": {
            {id.station}: station{},
            …
        }
    },
    "urls": {
        {id.station}: string,
        …
    }
}

GET /{station.string}?token={token.string}

{
    "status": status{},
    "response": station{
        "name": string,
        "slogan": string,
        "description": string,
        "images": [
            image{},
            …
        ],
        "coordinates": coordinates{
            "type": enum(non-profit, company, private),
            "organisation": string,
            "address": string,
            "zip": string,
            "city": string,
            "country": string,
            "phones": [
                phone{
                    "type": enum(main, direct, messaging, assistant, operator, studio, service, personal, professionnal, fax),
                    "number": string,
                    "description": string
                },
                …
            ],
            "emails": [
                email{
                    "type": enum(main, direct, messaging, assistant, operator, studio, service, personal, professionnal),
                    "email": string,
                    "description": string
                },
                …
            ]
        },
        "genres": [string, …],
        "urls": [
            url{},
            …
        ],
        "streams": [
            stream{
                "type": enum(main, redirect, proxy, other),
                "format": enum(mp3, aac, ogg),
                "quality": number,
                "channels": number,
                "url": string
            },
            …
        ],
        "extra": […]
    },
    "urls": {
        "stations": string,
        "show": string,
        "previous": string,
        "current": string,
        "next": string
    }
}

GET /{station.string}/show?token={token.string}

{
    "status": status{},
    "response": show{
        "name": string,
        "description": string,
        "bio": string,
        "recurrences": [
            recurrence{
                "days": [enum(mon, tue, wed, thu, fri, sat, sun), …],
                "dates": dates{
                    "start": "yyyy/mm/dd",
                    "end": "yyyy/mm/dd"
                },
                "hours": hours{
                    "start": "hh:mm",
                    "end": "hh:mm"
                }
            }
        ],
        "contributors": [
            contributor{
                "name": string,
                "roles": [enum(main, presenter, director, producer, community_manager, operator, webmaster, other), …],
                "images": [
                    image{},
                    …
                ],
                "urls": [
                    url{},
                    …
                ]
            }
        ]
    },
    "urls": {
        "station": string,
        "previous": string,
        "current": string,
        "next": string
    }
}

GET /{station.string}/show/{show.string}?token={token.string}

{
    "status": status{},
    "response": show{},
    "urls": {
        {id.station}: string,
    }
}

GET /{station.string}/artists?token={token.string}

{
    "status": status{},
    "response": [
        artist{},
        …
    ],
    "urls": {
        {id.station}: string
    }
}

GET /{station.string}/artists/{letter.string}?token={token.string}

{
    "status": status{},
    "response": [
        artist{},
        …
    ],
    "urls": {
        {id.station}: string
    }
}

GET /{station.string}/artist/{artist.string}?token={token.string}

{
    "status": status{},
    "response": [
        artist{},
        …
    ],
    "urls": {
        {id.station}: string
    }
}