Skip to content

Instantly share code, notes, and snippets.

@velsa

velsa/api-2.0.md

Last active August 29, 2015 14:17
Show Gist options
  • Save velsa/d1e3d55eabe582e33037 to your computer and use it in GitHub Desktop.
Save velsa/d1e3d55eabe582e33037 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
api-2.0.md

BACKEND API v2.0

Preface

A CRUD (Create/Read/Update and Delete) model is used for API access:

  • Create: HTTP POST request.
  • Read: HTTP GET request.
  • Update: HTTP PUT request.
  • Delete: HTTP DELETE request.

All Create (POST) and Update (PUT) requests must containt a JSON object with an appropriate :noun field (see below about nouns).

All replies will contain a similar JSON object, with the same :noun field. Replies have a special auxiliary field meta, which will contain information about the original request.

HTTP Response codes

Success:

| Code | Description | | ----- | ------------- | ----------- | | 200 | GET or PUT request completed successfully. Body of the reply contains requested or updated data. | | 201 | POST request completed successfully. Body of the reply is empty. | | 204 | DELETE or PUT request completed successfully. Body of the reply is empty. |

Error handling:

Errors are returned using standard HTTP error code syntax. Any additional info is included in the body of the return call, JSON-formatted. Error codes not listed here are in the REST API methods listed below.

| Code | Description | | ----- | ------------- | ----------- | | 400 | Bad input parameter. Error message should indicate which one and why. | | 403 | Bad OAuth request (wrong consumer key, bad nonce, expired timestamp...). Unfortunately, re-authenticating the user won't help here. | | 404 | Object not found. Returned when the specified :noun_id is not found in database. | | 405 | Request method not expected (generally should be GET, POST, PUT or DELETE). | | 429 | Your app is making too many requests and is being rate limited. 429s can trigger on a per-app or per-user basis. | | 500 | Internal Server error. | | 503 | If the response includes the Retry-After header, this means your OAuth 1.0 app is being rate limited. Otherwise, this indicates a transient server error, and your app should retry its request. | | 507 | User is over storage quota. |

URL format

URLs for Read (GET) requests always use :noun_plural:

movies
series, seasons, episodes
genres, persons

Example:

GET http://api.srv/2.0/movies

URLs for Create (POST), Update (PUT) and Delete (DELETE) requests always use :noun:

movie
serie, season, episode
genre, person

Example:

PUT http://api.srv/2.0/genre/action

Some special consideratons for query parameters in URL

Date and Time:

When passing a datetime, it should always be in ISO 8601 format:

yyyy-mm-ddThh-mm[-ss]

Here's a regexp, which can be used to validate the passed datetime:

/^\d{4}\-\d{2}\-\d{2}T\d{2}\-\d{2}(?:\-\d{2})?$/

Ranges:

When passing a number range (num range) or a date range (date range), the following syntax should be used: FROM[[..]TO]. E.g.:

  • 0 : just one number
  • 0..10: from 0 to 10 (inclusive)
  • 5..: from 0 to infinity (inclusive)
  • 2014-12-31T23-59..: from new year and till the end of times
  • ..2014-12-31T23-59: from beginning of time and till the new year

Reading Objects

Get list of Movies

Request:

http://api.srv/2.0/movies?arg1=val1&arg2=val2...

Argument Type Default Allowed values Description
offset int 0 0-... Skip this number of movies
limit int 10 1-100 Limit output to this number of movies
sort string added title, year, added, modified Sort by specified field. Default sort order is ASCENDING. Add - in front of the field to set DESCENDING sort order.
ids string,... none existing movie ids Get only movies with specified ids
genres string,... ALL existing genres Filter by genres
rating_from float 0.0 0.0 - 10.0 Only movies with IMDB rating higher than specified one
recommended boolean false false,true Filter by our own recommendations
likes num range ALL 0-... Filter by number of likes from our users
dislikes num range ALL 0-... Filter number of dislikes from our users
views num range ALL 0-... Filter by number of views from our users
added date range ALL Dates Filter by added time
modified date range ALL Dates Filter by last modification time
fields string,... ALL existing JSON fields JSON response will contain only the specified fields. NOTE: id is always returned in the response. You can also specify field names with - at the beginning, to exclude specific fields from JSON response.

Searching:

Argument Default Description
q=query_string none Performs search for specified query in some text fields: title, description, persons
q_type=match/exact/regex match Search query is match, exact match (exact) or regular expression

Response:

// JSON Response
{
    'meta': {
        'offset': Number,
        'limit': Number,
        'total': Number,
        'sort': String,
        'ids': String,
        'genres': String,
        'rating_from': String,
        'fields': String
    },
    'movies': [{
            'id': String,                       // ':movie_id'
            'title': String,
            'description': String,
            'snippet': String,                  // Title and description snippet (up to 120 chars)

            'imdb_id': String,

            'release_year': Number,
            'release_month': Number,
            'imdb_rating': Number,              // Float, e.g.: 4.5
            'duration': Number,                 // In minutes
            'genres': [String],
            'languages': [String],              // Reflects audio tracks of the movie.
                                                // First language is considered the main and default one. E.g.: [ 'en', 'de', 'ru' ]
            'mpaa': String,                     // MPAA rating, E.g. 'PG',
                                                // see: http://www.mpaa.org/film-ratings/
            'countries': [String],              // Countries participated in production
            'starring': [String],               // List of ':person_ids'
            'directors': [String],              // List of ':person_ids'

            'recommended': Boolean,             // Set to true by our admin/editor

            'images': {                         // Images for the Movie
                'image_type' : {image obj},    // available image types:
                ...                             // 'poster', 'backdrop', 'icon'
            },
            'web_links': {                      // Web links for this Movie
                'link_name': String,            // various useful urls
                ...                             // e.g. original torrent page, etc.
            },

            'magnet_hash': String,              // Unique magnet hash for this stream

            'streams': {
                'stream_type': {stream obj},    // Stream types:
                ...                             // 1920p, 1080p, 720p, 640p, 480p, 360p
            },

            'thumbnails': {                     // Urls to a thumbnails
                'thumb_type': String,           // Thumb types:
                ...                             // 'VTT', 'BIF'
            },

            'subtitles': {
                'language': String,             // Url to a subtitle file
                ...
            },

            'likes': Number,                    // Number of likes/dislikes from our users
            'dislikes': Number,
            'views': Number,                    // # of times the movie was watched

            'added': Date,                      // First added to DB
            'modified': Date,                   // Last modified
        },
        ...
    ]
}

Objects in response:

// Image info:
{
    'resolution': {                 // Resolution is the width of the image (?)
        'width': Number,
        'height': Number,
        'url': String,
    },
    ...
}

// Stream info
{
    'type': String,                 // 'HLS','DASH', 'MP4'
    'url': String,
    'audio': [
        {
            'language': String,
            'type': String,         // 'AC3', 'Stereo', 'Mono'
            'codec': String,        // 'AAC', 'MP3', 'OGG'
            'bitrate': Number       // in Kbit/s
        },
        ...
    ],
    'video': {
        'codec': String,            // 'H264 Baseline',
        'height': Number,
        'width': Number,
        'bitrate': Number           // in Kbit/s
    }
}

Get list of Genres

http://api.srv/2.0/genres?arg1=val1&arg2=val2...

Argument Type Default Allowed values Description
offset int 0 0-... Skip this number of genres
limit int 10 1-100 Limit output to this number of genres
sort string name name Sort by specified field. Default sort order is ASCENDING. Add - in front of the field to set DESCENDING sort order.
ids string,... none existing genre ids Get only genres with specified ids
fields string,... ALL existing JSON fields JSON response will contain only the specified fields. NOTE: id is always returned in the response. You can also specify field names with - at the beginning, to exclude specific fields from JSON response. 
// JSON Response
{
    'meta': {
        'offset': Number,
        'limit': Number,
        'total': Number,
        'order': String,
        'ids': String,
        'fields': String
    },
    'genres': [
        {
            'id': String,                       // ':genre_id'

            'name': String,                     // Genre name
            'description': String,              // Genre description
        },
        ...
    ]
}

Creating, Updating and Deleting objects

URLs

BASE URL: http://api.srv/2.0

Media:

Object Create (POST) Update (PUT) and Delete (DELETE)
Movie /movies /movies/:movie_id
Genre /genres /genres/:genre_id
Person /persons /persons/:person_id

Series (Сериалы)

BASE URL: http://api.srv/2.0/series

Object Create (POST) Update (PUT) and Delete (DELETE)
Series / /:serie_id
Seasons /:serie_id/seasons /:serie_id/seasons/:season_id
Episodes /:serie_id/seasons/:season_id/episodes /:serie_id/seasons/:season_id/episodes/:episode_id

JSON Requests and Responses

Create (POST):

// JSON Request
{
    'meta': {},
    ':noun': {
        // fields from corresponding ':noun_plural' MongoDB Schema
        ...
    }
}

// JSON Response
{
    'meta': {},
    ':noun': {
        'id': String,

        // fields from corresponding ':noun_plural' MongoDB Schema
        ...
    }
}

Update (PUT):

// JSON Request
{
    'meta': {},
    ':noun': {
        // fields that need modification
        // see corresponding ':noun_plural' MongoDB Schema
        ...
    }
}

// JSON Response
{
    'meta': {},
    ':noun': {
        'id': String,

        // fields from corresponding ':noun_plural' MongoDB Schema
        ...
    }
}

Delete (DELETE):

// JSON Request
{
    'meta': {}
}

// JSON Response
{
    'meta': {}
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment