initial proposal for the magneticow REST-ful HTTP API!

magneticow/README.rst

@@ -144,6 +144,15 @@ many GNU/Linux distributions):
 4. If you wish to see the logs, or to kill **magneticow**, ``screen -r magneticow`` will attach the original screen
    session back. **magneticow** will exit gracefully upon keyboard interrupt (Ctrl+C) [SIGINT].
 
+REST-ful HTTP API
+=================
+    **magneticow** offers a REST-ful HTTP API for 3rd-party applications to interact with **magnetico** setups. Examples
+    would be an Android app for searching torrents **magnetico** discovered and queueing them on your seedbox, or a
+    custom data analysis/statistics application developed for a research project on BitTorrent network. Nevertheless, it
+    is up to you what to do with it at the end of the day.
+
+See `API documentation <./docs/API/README.md>`_ for more details.
+
 License
 =======
 All the code is licensed under AGPLv3, unless otherwise stated in the source specific source. See ``COPYING`` file

magneticow/docs/API/README.md

@@ -0,0 +1,33 @@
+# magnetico<sup>w</sup> API Documentation
+
+**magneticow** offers a REST-ful HTTP API for 3rd-party applications to interact with **magnetico** setups. Examples
+would be an Android app for searching torrents **magnetico** discovered and queueing them on your seedbox, or a custom
+data analysis/statistics application developed for a research project on BitTorrent network. Nevertheless, it is up to
+you what to do with it at the end of the day.
+
+The rules stated above below to the API as a whole and across the all versions:
+
+* The API root is `/api`.
+* Right after the API root MUST come the API version in the format `vX` (*e.g.* `/api/v1`).
+* Different API versions MAY be backwards-incompatible, but any changes within the same version of the API MUST NOT
+  break the backwards-compatibility.
+* Version 0 (zero) of the API is considered to be experimental and MAY be backwards-incompatible.
+* API documentation MUST be considered as a contract between the developers of **magnetico** and **magneticow**, and of
+  3rd party application developers, and MUST be respected as such.
+
+The documentation for the API is organised as described below:
+
+* Each version of the API MUST be documented in a separate document named `vX.md`. Everything (*i.e.* each
+  functionality, status codes, etc.) MUST be clearly indicated when they are introduced.
+* Each document MUST clearly indicate at the beginning whether it is *finalized* or not. Not-finalised documents (called
+  *Draft*) CAN be changed, and finalised , but once finalised documents MUST NOT be modified afterwards.
+* Documentation for the version 0 (zero) of the API MUST be considered free from the rules above, and always considered
+  a *draft*.
+* Each document MUST be self-standing, that is, MUST be completely understandable and unambiguous without requiring to
+  refer another document.
+  * Hence, use quotations when necessary and reference them.
+
+Remarks:
+
+* Use British English, and serial comma.
+* Documents should be formatted in GitHub Flavoured Markdown.

magneticow/docs/API/v0.md

@@ -0,0 +1,93 @@
+# 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`.