# magnetico<sup>w</sup> 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](https://en.wikipedia.org/wiki/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`

```json
[
  {
    "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`

```json
[
  {
    "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`.