diff --git a/API.md b/API.md index 609977f..5e30d55 100644 --- a/API.md +++ b/API.md @@ -40,7 +40,9 @@ 3. [Resources](#resources) - [User](#user) + - [Tag category](#tag-category) - [Tag](#tag) + - [Snapshot](#snapshot) 4. [Search](#search) @@ -146,9 +148,9 @@ data. { "tagCategory": , "snapshots": [ - {"data": , "time": }, - {"data": , "time": }, - {"data": , "time": } + , + , + ] } ``` @@ -188,9 +190,9 @@ data. { "tagCategory": , "snapshots": [ - {"data": , "time": }, - {"data": , "time": }, - {"data": , "time": } + , + , + ] } ``` @@ -223,9 +225,9 @@ data. { "tagCategory": , "snapshots": [ - {"data": , "time": }, - {"data": , "time": }, - {"data": , "time": } + , + , + ] } ``` @@ -275,17 +277,15 @@ data. ```json5 { - "query": "haruhi", + "query": , // same as in input + "page": , // same as in input + "pageSize": , + "total": , "tags": [ - , - , , , - ], - "page": 1, - "pageSize": 5, - "total": 7 + ] } ``` ...where `` is a [tag resource](#tag) and `query` contains standard @@ -373,9 +373,9 @@ data. { "tag": , "snapshots": [ - {"data": , "time": }, - {"data": , "time": }, - {"data": , "time": } + , + , + ] } ``` @@ -427,9 +427,9 @@ data. { "tag": , "snapshots": [ - {"data": , "time": }, - {"data": , "time": }, - {"data": , "time": } + , + , + ] } ``` @@ -469,9 +469,9 @@ data. { "tag": , "snapshots": [ - {"data": , "time": }, - {"data": , "time": }, - {"data": , "time": } + , + , + ] } ``` @@ -519,8 +519,8 @@ data. ```json5 { - "remove": "source-tag", - "merge-to": "target-tag" + "remove": , + "merge-to": } ``` @@ -530,9 +530,9 @@ data. { "tag": , "snapshots": [ - {"data": , "time": }, - {"data": , "time": }, - {"data": , "time": } + , + , + ] } ``` @@ -565,11 +565,11 @@ data. "siblings": [ { "tag": , - "occurrences": 2 + "occurrences": }, { "tag": , - "occurrences": 1 + "occurrences": } ] } @@ -597,17 +597,17 @@ data. ```json5 { - "query": "rr-", + "query": , // same as in input + "page": , // same as in input + "pageSize": , + "total": , "users": [ , , , , - ], - "page": 1, - "pageSize": 5, - "total": 7 + ] } ``` ...where `` is a [user resource](#user) and `query` contains standard @@ -865,62 +865,171 @@ data. # Resources ## User +**Description** + +A single user. + +**Structure** ```json5 { - "name": "rr-", - "email": "rr-@sakuya.pl", // available only if the request is authenticated by the same user - "rank": "admin", // controlled by server's configuration - "rankName": "Administrator", // controlled by server's configuration - "lastLoginTime": "2016-04-08T20:20:16.570517", - "creationTime": "2016-03-28T13:37:01.755461", - "avatarStyle": "gravatar", // "gravatar" or "manual" - "avatarUrl": "http://gravatar.com/(...)" + "name": , + "email": , + "rank": , + "rankName": , + "lastLoginTime": , + "creationTime": , + "avatarStyle": , + "avatarUrl": } ``` +**Field meaning** +- ``: the user name. +- ``: the user email. It is available only if the request is + authenticated by the same user. +- ``: the user rank, which effectively affects their privileges. The + available ranks are stored in the server configuration. +- ``: the text representation of user's rank. Like ``, the + possible values depend on the server configuration. +- ``: the last login time, formatted as per RFC 3339. +- ``: the user registration time, formatted as per RFC 3339. +- ``: how to render the user avatar. + + Possible values: + + - `"gravatar"`: the user uses Gravatar. + - `"manual"`: the user has uploaded a picture manually. + +- ``: the URL to the avatar. + ## Tag category +**Description** + +A single tag category. The primary purpose of tag categories is to distinguish +certain tag types (such as characters, media type etc.), which improves user +experience. + +**Structure** ```json5 { - "name": "character", - "color": "#FF0000" // used to colorize certain tag types in the web client + "name": , + "color": } ``` -## Tag category snapshot +**Field meaning** -```json5 -{ - "name": "character", - "color": "#FF0000" -} -``` +- ``: the category name. +- ``: the category color. ## Tag +**Description** + +A single tag. Tags are used to let users search for posts. + +**Structure** ```json5 { - "names": ["tag1", "tag2", "tag3"], - "category": "plain", - "implications": ["implied-tag1", "implied-tag2", "implied-tag3"], - "suggestions": ["suggested-tag1", "suggested-tag2", "suggested-tag3"], - "creationTime": "2016-03-28T13:37:01.755461", - "lastEditTime": "2016-04-08T20:20:16.570517" + "names": , + "category": , + "implications": , + "suggestions": , + "creationTime": , + "lastEditTime": } ``` -## Tag snapshot +**Field meaning** + +- ``: a list of tag names (aliases). Tagging a post with any name will + automatically assign the first name from this list. +- ``: the name of the category the given tag belongs to. +- ``: a list of implied tag names. Implied tags are automatically + appended by the web client on usage. +- ``: a list of suggested tag names. Suggested tags are shown to + the user by the web client on usage. +- ``: time the tag was created, formatted as per RFC 3339. +- ``: time the tag was edited, formatted as per RFC 3339. + +## Snapshot +**Description** + +A snapshot is a version of a database resource. + +**Structure** ```json5 { - "names": ["tag1", "tag2", "tag3"], - "category": "plain", - "implications": ["imp1", "imp2", "imp3"], - "suggestions": ["sug1", "sug2", "sug3"] + "operation": , + "type": + "id": , + "user": , + "data": , + "earlier-data": , + "time":