Improved JSON API #12
Description
Currently the WPC API consists of a single endpoint with all of the information relating to streams, and AFAIK no way to get streamer information (something that WPC is starting to become concerned with). I would like to propose an improved REST API, with multiple end points and pagination for data intended to be tabulated. My first suggestion is that we break the API up into groups like:
- Streams
- Episodes
- Live streams
- Past streams
- Upcoming streams
- Streamers
This allows us to create a more readable and understandable API.
I'll present my proposed endpoints in the following format: <METHOD> <URI> --<comment>.
GET /api/streams/live
Get a paginated response containing live streams.
Response
{
"data": [
{"title": "Woah a stream", "user": "Reddit username of the streamer", "site": "where the user is streaming from", "id": "stream id", "series": "id of the series it belongs to"},
{"title": "Jims stream", "user": "billy", "site": "youtube", "id": "0x0001", "series": "0x10001"},
{"title": "Woah a stream", "user": "notch", "site": "twitch", "id": "0x0002", "series": "0x10002"}
],
"info": {
"pagination": {
"page": 0,
"max": 10
},
"status": 200
}
}GET /api/streams/upcoming
Get a paginated response containing upcoming streams
Response
{
"data": [
{"title": "Woah a stream", "user": "Reddit username of the streamer", "site": "where the user is streaming from", "id": "stream id", "series": "id of the series it belongs to"},
{"title": "Jims stream", "user": "billy", "site": "youtube", "id": "0x0001", "series": "0x10001"},
{"title": "Woah a stream", "user": "notch", "site": "twitch", "id": "0x0002", "series": "0x10002"}
],
"info": {
"pagination": {
"page": 0,
"max": 10
},
"status": 200
}
}GET /api/streams/past
Get a paginated response containing past streams
Response
{
"data": [
{"title": "Woah a stream", "user": "Reddit username of the streamer", "site": "where the user is streaming from", "id": "stream id", "series": "id of the series it belongs to"},
{"title": "Jims stream", "user": "billy", "site": "youtube", "id": "0x0001", "series": "0x10001"},
{"title": "Woah a stream", "user": "notch", "site": "twitch", "id": "0x0002", "series": "0x10002"}
],
"info": {
"pagination": {
"page": 0,
"max": 10
},
"status": 200
}
}GET /api/streams/{stream_id}
Get information on the stream with the specified ID
Response
{
"data": {"title": "Jims stream", "user": "billy", "site": "youtube", "id": "0x0001", "series": "0x10001"},
"info": {
"status": 200
}
}GET /api/streams/{stream_id}/episodes
Get all the related episodes of a set stream
Response
{
"data": [
{"title": "Episode 1", "user": "Reddit username of the streamer", "site": "where the user is streaming from", "id": "stream id", "series": "id of the series it belongs to"},
{"title": "Episode 2", "user": "billy", "site": "youtube", "id": "0x0001", "series": "0x10001"},
{"title": "Episode 3", "user": "notch", "site": "twitch", "id": "0x0002", "series": "0x10002"}
],
"info": {
"pagination": {
"page": 0,
"max": 10
},
"status": 200
}
}GET /api/streamer/{id}
Get information about a streamer
Response
{
"data": {
"user": "reddit username",
"aliases": {
"youtube": "bib",
"twitch": "bib_tv",
"hitbox": "bibin"
},
"about": "Oh yeah mate! I like stremin!"
}
}GET /api/streamer/{id}/series/
Get the series from a user
Response
{
"data": [
{"title": "Flask app", "id":"0x20001"},
{"title": "JavaScript madness!", "id":"0x20002"}
],
"info": {
"pagination": {
"page": 0,
"max": 2
},
"status": 200
}
}GET /api/streamer/{id}/upcoming
Get the upcoming streams of a specific user
Response
{
"data": [
{"title": "Woah a stream", "user": "Reddit username of the streamer", "site": "where the user is streaming from", "id": "stream id", "series": "id of the series it belongs to"},
{"title": "Jims stream", "user": "billy", "site": "youtube", "id": "0x0001", "series": "0x10001"},
{"title": "Woah a stream", "user": "notch", "site": "twitch", "id": "0x0002", "series": "0x10002"}
],
"info": {
"pagination": {
"page": 0,
"max": 10
},
"status": 200
}
}GET /api/streamer/{id}/live
Get the current stream that is being streamed from a user
Response
{
"data": {"title": "Woah a stream", "user": "Reddit username of the streamer", "site": "where the user is streaming from", "id": "stream id", "series": "id of the series it belongs to"},
"info": {
"status": 200
}
}GET /api/streamer/{id}/past
Get the past streams of a specific user
Response
{
"data": [
{"title": "Woah a stream", "user": "Reddit username of the streamer", "site": "where the user is streaming from", "id": "stream id", "series": "id of the series it belongs to"},
{"title": "Jims stream", "user": "billy", "site": "youtube", "id": "0x0001", "series": "0x10001"},
{"title": "Woah a stream", "user": "notch", "site": "twitch", "id": "0x0002", "series": "0x10002"}
],
"info": {
"pagination": {
"page": 0,
"max": 10
},
"status": 200
}
}