magnetico/magneticow/docs/API/v0.md

magnetico^w API v0 Documentation

Status: Draft (NOT Finalised)

Last Updated: 13 June 2017 by Bora M. Alper.

General remarks

• All requests MUST be encoded in UTF-8 and same applies for responses too.
  • Clients MUST set Content-type header to application/json; charset=utf-8 for all their requests.
• All dates MUST be in ISO 8601 format, same applies for responses too.

Collections

• /torrents, representing all the torrents in the database.
• /statistics, representing all the statistical data about the database.

Methods defined on /torrents collection

GET

Parameters:

• query: string to be queried in the torrent titles. If absent, all torrents will be returned.
  • ATTENTION: query MUST NOT be an empty string, if supplied.
  • Remark: The format of the query is to be clarified! [TODO]
• limit: number of results to be returned per page. If absent, it's by default 20.
• sort_by: string enum, MUST be one of the strings discovered_on, relevance (if query is non-empty), size, separated by space, and followed by one of the strings ASC or DESC, for ascending and descending, respectively.
  • ATTENTION: If sort_by is relevance, query is MUST be supplied.

Response:

• Status code: 200 OK

[
  {
    "info_hash": "ABCDEFABCDEFABCDEFAB",
    "title": "EXAMPLE TITLE",
    "discovered_on": "2017-06-13T14:06:01Z",
    "files": [
      {"path": "file.ext", "size": 1024},
      {"path": "directory/file_2.ext", "size": 2048},
      {"path": "directory/file_3.ext", "size": 4096},
      ...
    ]
  },
  ...
]

• info_hash is a hex-encoded info hash of the torrent.
• discovered_on is the date the torrent is discovered on.
  • ATTENTION: Due to ambiguities about time() function in the C standard library, the effect of leap seconds, and (being pedantic) even the epoch is platform-dependent. (The epoch is quite often 1970-01-01T00:00:00Z.)
• files is a list of files denoted by their relative-paths. / character (U+002F) is used as a path separator, hence it can be safely assumed that none of the directory or file name can contain it. \0 (U+0000) is also prohibited to appear anywhere in the path.
  • Remark: These restrictions are not in the BitTorrent specifications. So how magnetico enforces that? Well, magneticod simmply ignores torrents with illegal file names!

Methods defined on /statistics collection

GET

Parameters:

• group_by: is how data-points are grouped by; MUST be one of the strings hour, day, week, month, or year.
• period: is two dates, separated by a space chaacter (U+0020), denoting start and end, both inclusive.
  • ATTENTION: Depending on the group_by, datetime WILL be in one of the following formats:
    • yyyy for year (e.g. 2017)
    • yyyy-mm for month (e.g. 2017-06)
    • yyyy-Ww for week (e.g. 2017-W25)
    • yyyy-mm-dd for day (e.g. 2017-06-04)
    • yyyy-mm-ddThh for hour (e.g. 2017-06-04:02)

Response:

• Status code: 200 OK

[
  {
    "datetime": "2017-06",
    "new_torrents": 2591558
  },
  {
    "datetime": "2017-07",
    "new_torrents": 3448754
  },
  ...
]

• datetime is the date (and if applicable, time) of a data-point.
  • Remark: Depending on the group_by, datetime WILL have the same format with period.