diff --git a/API.md b/API.md index 83f0fc9..a6564b6 100644 --- a/API.md +++ b/API.md @@ -62,11 +62,18 @@ 3. [Resources](#resources) - [User](#user) + - [Detailed user](#detailed-user) - [Tag category](#tag-category) + - [Detailed tag category](#detailed-tag-category) - [Tag](#tag) + - [Detailed tag](#detailed-tag) - [Post](#post) + - [Detailed post](#detailed-post) - [Comment](#comment) + - [Detailed comment](#detailed-comment) - [Snapshot](#snapshot) + - [Unpaged search result](#unpaged-search-result) + - [Paged search result](#paged-search-result) 4. [Search](#search) @@ -126,16 +133,8 @@ data. - **Output** - ```json5 - { - "tagCategories": [ - , - , - - ] - } - ``` - ...where `` is a [tag category resource](#tag-category). + An [unpaged search result](#unpaged-search-result), for which `` + is a [tag category resource](#tag-category). - **Errors** @@ -168,18 +167,7 @@ data. - **Output** - ```json5 - { - "tagCategory": , - "snapshots": [ - , - , - - ] - } - ``` - ...where `` is a [tag category resource](#tag-category) and - `snapshots` contain its earlier versions. + A [detailed tag category resource](#detailed-tag-category). - **Errors** @@ -210,18 +198,7 @@ data. - **Output** - ```json5 - { - "tagCategory": , - "snapshots": [ - , - , - - ] - } - ``` - ...where `` is a [tag category resource](#tag-category) and - `snapshots` contain its earlier versions. + A [detailed tag category resource](#detailed-tag-category). - **Errors** @@ -245,18 +222,7 @@ data. - **Output** - ```json5 - { - "tagCategory": , - "snapshots": [ - , - , - - ] - } - ``` - ...where `` is a [tag category resource](#tag-category) and - `snapshots` contain its earlier versions. + A [detailed tag category resource](#detailed-tag-category). - **Errors** @@ -299,21 +265,8 @@ data. - **Output** - ```json5 - { - "query": , // same as in input - "page": , // same as in input - "pageSize": , - "total": , - "tags": [ - , - , - - ] - } - ``` - ...where `` is a [tag resource](#tag) and `query` contains standard - [search query](#search). + A [paged search result resource](#paged-search-result), for which + `` is a [tag resource](#tag). - **Errors** @@ -393,18 +346,7 @@ data. - **Output** - ```json5 - { - "tag": , - "snapshots": [ - , - , - - ] - } - ``` - ...where `` is a [tag resource](#tag) and `snapshots` contain its - earlier versions. + A [detailed tag resource](#detailed-tag). - **Errors** @@ -447,18 +389,7 @@ data. - **Output** - ```json5 - { - "tag": , - "snapshots": [ - , - , - - ] - } - ``` - ...where `` is a [tag resource](#tag) and `snapshots` contain its - earlier versions. + A [detailed tag resource](#detailed-tag). - **Errors** @@ -489,18 +420,7 @@ data. - **Output** - ```json5 - { - "tag": , - "snapshots": [ - , - , - - ] - } - ``` - ...where `` is a [tag resource](#tag) and `snapshots` contain its - earlier versions. + A [detailed tag resource](#detailed-tag). - **Errors** @@ -550,18 +470,7 @@ data. - **Output** - ```json5 - { - "tag": , - "snapshots": [ - , - , - - ] - } - ``` - ...where `` is the target [tag resource](#tag) and `snapshots` - contain its earlier versions. + A [detailed tag resource](#detailed-tag) containing the merged tag. - **Errors** @@ -619,23 +528,7 @@ data. - **Output** - ```json5 - { - "post": , - "snapshots": { - , - , - - }, - "comments": { - , - , - - } - } - ``` - ...where `` is a [post resource](#post), `` is a [comment - resource](#comment) and `snapshots` contain post's earlier versions. + A [detailed post resource](#detailed-post). - **Errors** @@ -683,12 +576,7 @@ data. - **Output** - ```json5 - { - "post": - } - ``` - ...where `` is a [post resource](#post). + A [detailed post resource](#detailed-post). - **Errors** @@ -709,18 +597,7 @@ data. - **Output** - ```json5 - { - "post": , - "snapshots": [ - , - , - - ] - } - ``` - ...where `` is a [post resource](#post) and `snapshots` contain its - earlier versions. + A [detailed post resource](#detailed-post). - **Errors** @@ -740,18 +617,7 @@ data. - **Output** - ```json5 - { - "post": , - "snapshots": [ - , - , - - ] - } - ``` - ...where `` is a [post resource](#post) and `snapshots` contain its - earlier versions. + A [detailed post resource](#detailed-post). - **Errors** @@ -770,21 +636,8 @@ data. - **Output** - ```json5 - { - "query": , // same as in input - "page": , // same as in input - "pageSize": , - "total": , - "comments": [ - , - , - - ] - } - ``` - ...where `` is a [comment resource](#comment) and `query` contains - standard [search query](#search). + A [paged search result resource](#paged-search-result), for which + `` is a [comment resource](#comment). - **Errors** @@ -848,12 +701,7 @@ data. - **Output** - ```json5 - { - "comment": - } - ``` - ...where `` is a [comment resource](#comment). + A [detailed comment resource](#detailed-comment). - **Errors** @@ -881,12 +729,7 @@ data. - **Output** - ```json5 - { - "comment": - } - ``` - ...where `` is a [comment resource](#comment). + A [detailed comment resource](#detailed-comment). - **Errors** @@ -906,12 +749,7 @@ data. - **Output** - ```json5 - { - "comment": - } - ``` - ...where `` is a [comment resource](#comment). + A [detailed comment resource](#detailed-comment). - **Errors** @@ -959,12 +797,7 @@ data. - **Output** - ```json5 - { - "comment": - } - ``` - ...where `` is a [comment resource](#comment). + A [detailed comment resource](#detailed-comment). - **Errors** @@ -985,21 +818,8 @@ data. - **Output** - ```json5 - { - "query": , // same as in input - "page": , // same as in input - "pageSize": , - "total": , - "users": [ - , - , - - ] - } - ``` - ...where `` is a [user resource](#user) and `query` contains standard - [search query](#search). + A [paged search result resource](#paged-search-result), for which + `` is a [user resource](#user). - **Errors** @@ -1066,12 +886,7 @@ data. - **Output** - ```json5 - { - "user": - } - ``` - ...where `` is a [user resource](#user). + A [detailed user resource](#detailed-user). - **Errors** @@ -1118,12 +933,7 @@ data. - **Output** - ```json5 - { - "user": - } - ``` - ...where `` is a [user resource](#user). + A [detailed user resource](#detailed-user). - **Errors** @@ -1153,12 +963,7 @@ data. - **Output** - ```json5 - { - "user": - } - ``` - ...where `` is a [user resource](#user). + A [detailed user resource](#detailed-user). - **Errors** @@ -1256,21 +1061,8 @@ data. - **Output** - ```json5 - { - "query": , // same as in input - "page": , // same as in input - "pageSize": , - "total": , - "snapshots": [ - , - , - - ] - } - ``` - ...where `` is a [snapshot resource](#snapshot) and `query` - contains standard [search query](#search). + A [paged search result resource](#paged-search-result), for which + `` is a [snapshot resource](#snapshot). - **Errors** @@ -1367,6 +1159,23 @@ A single user. - ``: the URL to the avatar. +## Detailed user +**Description** + +A wrapper for a user. In the future, it might offer extra information. + +**Structure** + +```json5 +{ + "user": +} +``` + +**Field meaning** + +- ``: a [user resource](#user). + ## Tag category **Description** @@ -1388,6 +1197,30 @@ experience. - ``: the category name. - ``: the category color. +## Detailed tag category +**Description** + +A tag category with extra information. + +**Structure** + +```json5 +{ + "tagCategory": , + "snapshots": [ + , + , + + ] +} +``` + +**Field meaning** + +- ``: a [tag category resource](#tag-category) +- ``: a [snapshot resource](#snapshot) that contains the tag + category's earlier versions. + ## Tag **Description** @@ -1418,6 +1251,29 @@ A single tag. Tags are used to let users search for posts. - ``: time the tag was created, formatted as per RFC 3339. - ``: time the tag was edited, formatted as per RFC 3339. +## Detailed tag +**Description** + +A tag with extra information. + +**Structure** + +```json5 +{ + "tag": , + "snapshots": [ + , + , + + ] +} +``` + +**Field meaning** +- ``: a [tag resource](#tag) +- ``: a [snapshot resource](#snapshot) that contains the tag's + earlier versions. + ## Post **Description** @@ -1444,7 +1300,7 @@ One file together with its metadata posted to the site. "ownScore": , "favoritedBy": , "featureCount": , - "lastFeatureTime": , + "lastFeatureTime": } ``` @@ -1490,6 +1346,35 @@ One file together with its metadata posted to the site. - ``: the last time the post was featured, formatted as per RFC 3339. +## Detailed post +**Description** + +A post with extra information. + +**Structure** + +```json5 +{ + "post": , + "snapshots": [ + , + , + + ], + "comments": { + , + , + + } +} +``` + +**Field meaning** +- ``: a [post resource](#post). +- ``: a [snapshot resource](#snapshot) that contains the post's + earlier versions. +- ``: a [comment resource](#comment) for given post. + ## Comment **Description** @@ -1520,6 +1405,21 @@ A comment under a post. - ``: the score (+1/-1 rating) of the given comment by the authenticated user. +## Detailed comment +**Description** + +A wrapper for a comment. In the future, it might offer extra information. + +**Structure** + +```json5 +{ + "comment": +} +``` + +**Field meaning** +- ``: a [comment resource](#comment). ## Snapshot **Description** @@ -1614,6 +1514,58 @@ A snapshot is a version of a database resource. - `