Torrent Service Documentation¶

The torrent service is quite simple. It gets information from http://torrentapi.org/ for a specific category (or all categories at once). This returns an array of torrents which is sorted by seeds (meaning those that are being shared the most). The service gets the top 7 of these and processes them into a formated dictionary, see GET /categories/(category) for an example. The service then returns these as a list of JSON objects to the user.

While processing the torrents, if one is encountered that has category of movies or of TV-series then the service will automatically ask http://www.omdbapi.com/ for extra information about them (once again, see GET /categories/(category) for an example). This extra information will be added to the respective JSON object and will be sent with the data as part of the response.

Required Authentication¶

Anyone can consume the torrent service without need of authentication. However, the torrent service does need to authenticate with both http://torrentapi.org/ and http://www.omdbapi.com/.

http://www.omdbapi.com/ requires one to sign up and obtain an API key which we just need to send with every request we make as part of the request parameters.

For http://torrentapi.org/ we ask for a token programatically. This token expires after a certain period of time so we need to monitor that it is still valid and renew it if needed. For torrentapi we also need to specify an application name which authenticates us with the service.

Endpoint Reference Table¶

Resource	Operation	Description
Get Categories	GET /categories	Returns the supported categories.
Get Category Information	GET /categories/(category)	Returns top torrents for the specified category.

Endpoint Documentation¶

GET /categories¶

Returns the supported categories. This is basically always the same content, and the categories are hardcoded in the service, so that is why it is not possible for this to fail.

Example request:

GET /categories HTTP/1.1
Host: https://torrent-service-sde.herokuapp.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "categories": [
        "software",
        "ebooks",
        "movies",
        "TV-series",
        "music",
        "games",
        "all"
    ]
}

Status Codes:	200 OK – able to list categories

GET /categories/(category)¶

Asks the torrent information provider for torrents about the specified category and returns top torrents as dictionaries with the keys already properly formatted. If the specified category is either movie or TV-series then the service will also include IMDB information as part of the return data.

For all categories the service returns: Title, Seeders, and Leechers. When the category is movie or TV-series then the service also returns the following information for each torrent:

Runtime
Genre
Director
Awards
Rating
Plot

This service only returns data on the top 7 torrents.

Example request:

GET /categories/movies HTTP/1.1
Host: https://torrent-service-sde.herokuapp.com
Accept: application/json

Example response: (note that we’re only showing one result in the response, so as to save space, but usually there would be 7)

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
    "data": [
        {
            "Title": "The Girl in the Spider's Web",
            "Seeders": 5644,
            "Leechers": 2568,
            "Runtime": "117 min",
            "Genre": "Action, Crime, Drama, Thriller",
            "Director": "Fede Alvarez",
            "Awards": "N/A",
            "Rating (IMDB)": "6.1",
            "Plot": "Young computer hacker Lisbeth Salander and journalist Mikael Blomkvist find themselves caught in a web of spies, cybercriminals and corrupt government officials."
        },

    ]
}

Query Parameters:
	category – the category we’re interested in getting information about
Status Codes:	400 Bad Request – the specified category is not valid 200 OK – data for category has been successfully found