94 lines
3.4 KiB
Markdown
94 lines
3.4 KiB
Markdown
# 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`.
|