Improved JSON API

[paked]

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
    }
}

[lurraca]

+1!

[jniebuhr]

i'm on it :P

[jniebuhr]

I have changed /api/streamer/ to always be /api/streamers/

[jniebuhr]

I've put a documentation of the current state in the wiki: https://github.com/WatchPeopleCode/WatchPeopleCode/wiki/API-Documentation