ulysia/szurubooru
Archived
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated and polished documentation

Browse source
This commit is contained in:
Luxray5474 2020-08-24 21:01:04 -04:00
parent 955328735f
commit 04169c6942
2 changed files with 390 additions and 257 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
client/html/help_search_posts.tpl
View file

@ -24,11 +24,11 @@
</tr> </tr>
<tr> <tr>
<td><code> upload</code></td> <td><code> upload</code></td>
<td>alias of <code>upload</code></td> <td>alias of <code>uploader</code></td>
</tr> </tr>
<tr> <tr>
<td><code> submit</code></td> <td><code> submit</code></td>
<td>alias of <code>upload</code></td> <td>alias of <code>uploader</code></td>
</tr> </tr>
<tr> <tr>
<td><code>comment</code></td> <td><code>comment</code></td>
@ -146,6 +146,22 @@
<td><code> time</code></td> <td><code> time</code></td>
<td>alias of <code>creation-date</code></td> <td>alias of <code>creation-date</code></td>
</tr> </tr>
<tr>
<td><code>file-last-modified-time</code></td>
<td>source file last modified at a given date</td>
</tr>
<tr>
<td><code> file-modified</code></td>
<td>alias of <code>file-last-modified-time</code></td>
</tr>
<tr>
<td><code> source-modified</code></td>
<td>alias of <code>file-last-modified-time</code></td>
</tr>
<tr>
<td><code> flmt</code></td>
<td>alias of <code>file-last-modified-time</code></td>
</tr>
<tr> <tr>
<td><code>last-edit-date</code></td> <td><code>last-edit-date</code></td>
<td>edited at given date</td> <td>edited at given date</td>
@ -281,6 +297,22 @@
<td><code> time</code></td> <td><code> time</code></td>
<td>alias of <code>creation-date</code></td> <td>alias of <code>creation-date</code></td>
</tr> </tr>
<tr>
<td><code>file-last-modified-time</code></td>
<td>newest to oldest based on source file's last modified time</td>
</tr>
<tr>
<td><code> file-modified</code></td>
<td>alias of <code>file-last-modified-time</code></td>
</tr>
<tr>
<td><code> source-modified</code></td>
<td>alias of <code>file-last-modified-time</code></td>
</tr>
<tr>
<td><code> flmt</code></td>
<td>alias of <code>file-last-modified-time</code></td>
</tr>
<tr> <tr>
<td><code>last-edit-date</code></td> <td><code>last-edit-date</code></td>
<td>like <code>creation-date</code>, only looks at last edit time</td> <td>like <code>creation-date</code>, only looks at last edit time</td>

315
doc/API.md
View file

@ -337,9 +337,11 @@ data.
- **Description** - **Description**
Creates a new tag category using specified parameters. Name must match Creates a new tag category using specified parameters.
`tag_category_name_regex` from server's configuration. First category
created becomes the default category. * Name must match `tag_category_name_regex` from tje server's configuration.
* First category created becomes the default category.
## Updating tag category ## Updating tag category
- **Request** - **Request**
@ -371,10 +373,12 @@ data.
- **Description** - **Description**
Updates an existing tag category using specified parameters. Name must Updates an existing tag category using specified parameters.
match `tag_category_name_regex` from server's configuration. All fields
except the [`version`](#versioning) are optional - update concerns only * Name must match `tag_category_name_regex` from server's configuration.
provided fields.
* All fields except the [`version`](#versioning) are optional - update
concerns only provided fields.
## Getting tag category ## Getting tag category
- **Request** - **Request**
@ -547,15 +551,21 @@ data.
- **Description** - **Description**
Creates a new tag using specified parameters. Names, suggestions and Creates a new tag using specified parameters.
implications must match `tag_name_regex` from server's configuration.
Category must exist and is the same as `name` field within * Names, suggestions and implications must match `tag_name_regex` from
[`<tag-category>` resource](#tag-category). Suggestions and implications the server's configuration.
are optional. If specified implied tags or suggested tags do not exist yet,
they will be automatically created. Tags created automatically have no * Category must exist and must be the same as `name` field within
implications, no suggestions, one name and their category is set to the [`<tag-category>` resource](#tag-category).
first tag category found. If there are no tag categories established yet,
an error will be thrown. * Suggestions and implications are optional.
* If specified implied tags or suggested tags do not exist yet, they will
be automatically created. Tags created automatically have no implications,
no suggestions, one name and their category is set to the first tag
category found. If there are no tag categories established yet, an error
will be thrown.
## Updating tag ## Updating tag
- **Request** - **Request**
@ -592,15 +602,21 @@ data.
- **Description** - **Description**
Updates an existing tag using specified parameters. Names, suggestions and Updates an existing tag using specified parameters.
implications must match `tag_name_regex` from server's configuration.
Category must exist and is the same as `name` field within * Names, suggestions and implications must match `tag_name_regex` from
[`<tag-category>` resource](#tag-category). If specified implied tags or the server's configuration.
suggested tags do not exist yet, they will be automatically created. Tags
created automatically have no implications, no suggestions, one name and * Category must exist and must be the the same as `name` field within
their category is set to the first tag category found. All fields except [`<tag-category>` resource](#tag-category).
the [`version`](#versioning) are optional - update concerns only provided
fields. * If specified implied tags or suggested tags do not exist yet, they will
be automatically created. Tags created automatically have no implications,
no suggestions, one name and their category is set to the first tag
category found.
* All fields except the [`version`](#versioning) are optional - update
concerns only provided fields.
## Getting tag ## Getting tag
- **Request** - **Request**
@ -712,9 +728,12 @@ data.
- **Description** - **Description**
Lists siblings of given tag, e.g. tags that were used in the same posts as Lists siblings of given tag, e.g. tags that were used in the same posts as
the given tag. `occurrences` field signifies how many times a given sibling the given tag. `occurrences`
appears with given tag. Results are sorted by occurrences count and the
list is truncated to the first 50 elements. Doesn't use paging. * Field signifies how many times a given sibling appears with given tag.
* Results are sorted by occurrences count and the list is truncated to the
first 50 elements. Doesn't use paging.
## Listing posts ## Listing posts
- **Request** - **Request**
@ -741,7 +760,7 @@ data.
**Named tokens** **Named tokens**
| `<key>` | Description | | `<key>` | Description |
| -------------------- | ---------------------------------------------------------- | | ------------------------- | ---------------------------------------------------------- |
| `id` | having given post number | | `id` | having given post number |
| `tag` | having given tag (accepts wildcards) | | `tag` | having given tag (accepts wildcards) |
| `score` | having given score | | `score` | having given score |
@ -775,6 +794,10 @@ data.
| `creation-time` | alias of `creation-date` | | `creation-time` | alias of `creation-date` |
| `date` | alias of `creation-date` | | `date` | alias of `creation-date` |
| `time` | alias of `creation-date` | | `time` | alias of `creation-date` |
| `file-last-modified-time` | source file last modified at given date, based on file metadata |
| `file-modified` | alias of `file-last-modified-time` |
| `source-modified` | alias of `file-last-modified-time` |
| `flmt` | alias of `file-last-modified-time` |
| `last-edit-date` | edited at given date | | `last-edit-date` | edited at given date |
| `last-edit-time` | alias of `last-edit-date` | | `last-edit-time` | alias of `last-edit-date` |
| `edit-date` | alias of `last-edit-date` | | `edit-date` | alias of `last-edit-date` |
@ -791,7 +814,7 @@ data.
**Sort style tokens** **Sort style tokens**
| `<value>` | Description | | `<value>` | Description |
| ---------------- | ------------------------------------------------ | | ------------------------- | ---------------------------------------------------------- |
| `random` | as random as it can get | | `random` | as random as it can get |
| `id` | highest to lowest post number | | `id` | highest to lowest post number |
| `score` | highest scored | | `score` | highest scored |
@ -812,6 +835,10 @@ data.
| `creation-time` | alias of `creation-date` | | `creation-time` | alias of `creation-date` |
| `date` | alias of `creation-date` | | `date` | alias of `creation-date` |
| `time` | alias of `creation-date` | | `time` | alias of `creation-date` |
| `file-last-modified-time` | newest to oldest based on source file's last modified time |
| `file-modified` | alias of `file-last-modified-time` |
| `source-modified` | alias of `file-last-modified-time` |
| `flmt` | alias of `file-last-modified-time` |
| `last-edit-date` | like creation-date, only looks at last edit time | | `last-edit-date` | like creation-date, only looks at last edit time |
| `last-edit-time` | alias of `last-edit-date` | | `last-edit-time` | alias of `last-edit-date` |
| `edit-date` | alias of `last-edit-date` | | `edit-date` | alias of `last-edit-date` |
@ -847,7 +874,8 @@ data.
"relations": [<post1>, <post2>, <post3>], // optional "relations": [<post1>, <post2>, <post3>], // optional
"notes": [<note1>, <note2>, <note3>], // optional "notes": [<note1>, <note2>, <note3>], // optional
"flags": [<flag1>, <flag2>], // optional "flags": [<flag1>, <flag2>], // optional
"anonymous": <anonymous> // optional "anonymous": <anonymous>, // optional
"fileLastModifiedTime": <timestamp> // optional
} }
``` ```
@ -869,17 +897,33 @@ data.
- **Description** - **Description**
Creates a new post. If specified tags do not exist yet, they will be Creates a new post.
automatically created. Tags created automatically have no implications, no
suggestions, one name and their category is set to the first tag category * If specified tags do not exist yet, they will be automatically created.
found. Safety must be any of `"safe"`, `"sketchy"` or `"unsafe"`. Relations Tags created automatically have no implications, no suggestions, one name
must contain valid post IDs. If `<flag>` is omitted, they will be defined and their category is set to the first tag category found.
by default (`"loop"` will be set for all video posts, and `"sound"` will be
auto-detected). Sending empty `thumbnail` will cause the post to use default * Safety must be any of `"safe"`, `"sketchy"` or `"unsafe"`.
thumbnail. If `anonymous` is set to truthy value, the uploader name won't be
* Relations must contain valid post IDs.
* If `<flag>` is omitted, they will be defined by default. (`"loop"` will
be set for all video posts, and `"sound"` will be auto-detected).
* Sending empty `thumbnail` will cause the post to use default thumbnail.
* If `anonymous` is `true`, the uploader name won't be
recorded (privilege verification still applies; it's possible to disallow recorded (privilege verification still applies; it's possible to disallow
anonymous uploads completely from config.) For details on how to pass `content` anonymous uploads completely from config.)
and `thumbnail`, see [file uploads](#file-uploads).
* If `file-last-modified-time` is omitted, the time the post is updated
will be used instead. Its value must be a UNIX timestamp **in
milliseconds**. This parameter is made available to the client to allow for
placing custom times. **Note that this parameter cannot be changed until
the next time the content of the post is updated.**
*For details on how to pass `content` and `thumbnail`, see
[file uploads](#file-uploads).*
## Updating post ## Updating post
- **Request** - **Request**
@ -896,7 +940,8 @@ data.
"source": <source>, // optional "source": <source>, // optional
"relations": [<post1>, <post2>, <post3>], // optional "relations": [<post1>, <post2>, <post3>], // optional
"notes": [<note1>, <note2>, <note3>], // optional "notes": [<note1>, <note2>, <note3>], // optional
"flags": [<flag1>, <flag2>] // optional "flags": [<flag1>, <flag2>], // optional
"fileLastModifiedTime": <file-last-modified-time> // optional
} }
``` ```
@ -919,16 +964,36 @@ data.
- **Description** - **Description**
Updates existing post. If specified tags do not exist yet, they will be Updates an existing post.
automatically created. Tags created automatically have no implications, no
suggestions, one name and their category is set to the first tag category * If specified tags do not exist yet, they will be automatically created.
found. Safety must be any of `"safe"`, `"sketchy"` or `"unsafe"`. Relations Tags created automatically have no implications, no suggestions, one name
must contain valid post IDs. `<flag>` can be either `"loop"` to enable looping and their category is set to the first tag category found.
for video posts or `"sound"` to indicate sound. Sending empty `thumbnail` will
reset the post thumbnail to default. For details how to pass `content` and * Safety must be any of `"safe"`, `"sketchy"` or `"unsafe"`.
`thumbnail`, see [file uploads](#file-uploads). All fields except the
[`version`](#versioning) are optional - update concerns only provided * Relations must contain valid post IDs.
fields.
* If `<flag>` is omitted, they will be defined by default. (`"loop"` will
be set for all video posts, and `"sound"` will be auto-detected).
* Sending empty `thumbnail` will cause the post to use default thumbnail.
* If `anonymous` is `true`, the uploader name won't be
recorded (privilege verification still applies; it's possible to disallow
anonymous uploads completely from config.)
* If `file-last-modified-time` is omitted, the time the post is created
will be used instead. Its value must be a UNIX timestamp **in
milliseconds**. This parameter is made available to the client to allow for
placing custom times. **Note that this parameter cannot be changed until
the next time the content of the post is updated.**
* All fields except the [`version`](#versioning) are optional - update
concerns only provided fields.
*For details on how to pass `content` and `thumbnail`, see
[file uploads](#file-uploads).*
## Getting post ## Getting post
- **Request** - **Request**
@ -1008,11 +1073,13 @@ data.
- **Description** - **Description**
Removes source post and merges all of its tags, relations, scores, Removes source post and merges all of its tags, relations, scores,
favorites and comments to the target post. If `replaceContent` is set to favorites and comments to the target post.
true, content of the target post is replaced using the content of the
source post; otherwise it remains unchanged. Source post properties such as * If `replaceContent` is set to true, content of the target post is
its safety, source, whether to loop the video and other scalar values do replaced using the content of the *source post*; otherwise it remains
not get transferred and are discarded. unchanged. Source post properties such as its safety, source, whether to
loop the video and other scalar values do not get transferred and are
discarded.
## Rating post ## Rating post
- **Request** - **Request**
@ -1094,9 +1161,11 @@ data.
- **Description** - **Description**
Retrieves the post that is currently featured on the main page in web Retrieves the post that is currently featured on the main page in web
client. If no post is featured, `<post>` is null. Note that this method client.
exists mostly for compatibility with setting featured post - most of times,
you'd want to use query global info which contains more information. * If no post is featured, `<post>` is null. Note that this method
exists mostly for compatibility with setting featured post - most of the
time, you'd want to query global info which contains more information.
## Featuring post ## Featuring post
- **Request** - **Request**
@ -1190,9 +1259,11 @@ data.
- **Description** - **Description**
Creates a new pool category using specified parameters. Name must match Creates a new pool category using specified parameters.
`pool_category_name_regex` from server's configuration. First category
created becomes the default category. * Name must match `pool_category_name_regex` from server's configuration.
* First category created becomes the default category.
## Updating pool category ## Updating pool category
- **Request** - **Request**
@ -1224,10 +1295,12 @@ data.
- **Description** - **Description**
Updates an existing pool category using specified parameters. Name must Updates an existing pool category using specified parameters.
match `pool_category_name_regex` from server's configuration. All fields
except the [`version`](#versioning) are optional - update concerns only * Name must match `pool_category_name_regex` from server's configuration.
provided fields.
* All fields except the [`version`](#versioning) are optional - update
concerns only provided fields.
## Getting pool category ## Getting pool category
- **Request** - **Request**
@ -1390,12 +1463,16 @@ data.
- **Description** - **Description**
Creates a new pool using specified parameters. Names, suggestions and Creates a new pool using specified parameters.
implications must match `pool_name_regex` from server's configuration.
Category must exist and is the same as `name` field within * Names, suggestions and implications must match `pool_name_regex` from
[`<pool-category>` resource](#pool-category). `posts` is an optional list of server's configuration.
integer post IDs. If the specified posts do not exist, an error will be
thrown. * Category must exist and is the same as `name` field within
[`<pool-category>` resource](#pool-category).
* `posts` is an optional list of integer post IDs. If the specified posts
do not exist, an error will be thrown.
## Updating pool ## Updating pool
- **Request** - **Request**
@ -1431,14 +1508,20 @@ data.
- **Description** - **Description**
Updates an existing pool using specified parameters. Names, suggestions and Updates an existing pool using specified parameters.
implications must match `pool_name_regex` from server's configuration.
Category must exist and is the same as `name` field within * Names, suggestions and implications must match `pool_name_regex` from
[`<pool-category>` resource](#pool-category). `posts` is an optional list of server's configuration.
integer post IDs. If the specified posts do not exist yet, an error will be
thrown. The full list of post IDs must be provided if they are being * Category must exist and is the same as `name` field within
updated, and the previous list of posts will be replaced with the new one. [`<pool-category>` resource](#pool-category).
All fields except the [`version`](#versioning) are optional - update
* `posts` is an optional list of integer post IDs. If the specified posts
do not exist yet, an error will be thrown. The full list of post IDs must
be provided if they are being updated, and the previous list of posts will
be replaced with the new one.
* All fields except the [`version`](#versioning) are optional - update
concerns only provided fields. concerns only provided fields.
## Getting pool ## Getting pool
@ -1798,12 +1881,16 @@ data.
- **Description** - **Description**
Creates a new user using specified parameters. Names and passwords must Creates a new user using specified parameters.
match `user_name_regex` and `password_regex` from server's configuration,
respectively. Email address, rank and avatar fields are optional. Avatar * Names and passwords must match `user_name_regex` and `password_regex`
style can be either `gravatar` or `manual`. `manual` avatar style requires from server's configuration, respectively.
client to pass also `avatar` file - see [file uploads](#file-uploads) for
details. If the rank is empty and the user happens to be the first user * Email address, rank and avatar fields are optional. Avatar style can be
either `gravatar` or `manual`. `manual` avatar style also requires client
to pass `avatar` file - see [file uploads](#file-uploads) for details.
* If the rank is empty and the user happens to be the first user
ever created, become an administrator, whereas subsequent users will be ever created, become an administrator, whereas subsequent users will be
given the rank indicated by `default_rank` in the server's configuration. given the rank indicated by `default_rank` in the server's configuration.
@ -1846,15 +1933,19 @@ data.
- **Description** - **Description**
Updates an existing user using specified parameters. Names and passwords Updates an existing user using specified parameters.
must match `user_name_regex` and `password_regex` from server's
configuration, respectively. All fields are optional - update concerns only * All fields except the [`version`](#versioning) are optional - update
provided fields. To update last login time, see concerns only provided fields.
[authentication](#authentication). Avatar style can be either `gravatar` or
`manual`. `manual` avatar style requires client to pass also `avatar` * Names and passwords must match `user_name_regex` and `password_regex`
file - see [file uploads](#file-uploads) for details. All fields except the from server's configuration, respectively.
[`version`](#versioning) are optional - update concerns only provided
fields. * To update last login time, see [authentication](#authentication).
* Avatar style can be either `gravatar` or `manual`. `manual` avatar style
also requires client to pass `avatar` file - see
[file uploads](#file-uploads) for details.
## Getting user ## Getting user
- **Request** - **Request**
@ -2027,11 +2118,12 @@ data.
- **Description** - **Description**
Sends a confirmation email to given user. The email contains link Sends a confirmation email to given user.
containing a token. The token cannot be guessed, thus using such link
proves that the person who requested to reset the password also owns the * The email contains link containing a token. The token cannot be guessed,
mailbox, which is a strong indication they are the rightful owner of the thus using such link proves that the person who requested to reset the
account. password also owns the mailbox, which is a strong indication they are the
rightful owner of the account.
## Password reset - step 2: confirmation ## Password reset - step 2: confirmation
- **Request** - **Request**
@ -2134,12 +2226,16 @@ data.
- **Description** - **Description**
Retrieves simple statistics. `<featured-post>` is null if there is no Retrieves simple statistics.
featured post yet. `<server-time>` is pretty much the same as the `Date`
HTTP field, only formatted in a manner consistent with other dates. Values * `<featured-post>` is null if there is no featured post yet.
in `config` key are taken directly from the server config, with the
exception of privilege array keys being converted to lower camel case to * `<server-time>` is pretty much the same as the `Date` HTTP field, only
match the API convention. formatted in a manner consistent with other dates.
* Values in `config` key are taken directly from the server config, with
the exception of privilege array keys being converted to lower camel case
to match the API convention.
## Uploading temporary file ## Uploading temporary file
@ -2356,6 +2452,7 @@ One file together with its metadata posted to the site.
"version": <version>, "version": <version>,
"id": <id>, "id": <id>,
"creationTime": <creation-time>, "creationTime": <creation-time>,
"fileLastModifiedTime": <file-last-modified-time>,
"lastEditTime": <last-edit-time>, "lastEditTime": <last-edit-time>,
"safety": <safety>, "safety": <safety>,
"source": <source>, "source": <source>,
@ -2396,6 +2493,10 @@ One file together with its metadata posted to the site.
- `<version>`: resource version. See [versioning](#versioning). - `<version>`: resource version. See [versioning](#versioning).
- `<id>`: the post identifier. - `<id>`: the post identifier.
- `<creation-time>`: time the tag was created, formatted as per RFC 3339. - `<creation-time>`: time the tag was created, formatted as per RFC 3339.
- `<file-last-modified-time>`: in uploading, this is a UNIX timestamp in
milliseconds. After the post has been created, this represents the last time
the source file was modified based on file metadata, formatted as per RFC
3339.
- `<last-edit-time>`: time the tag was edited, formatted as per RFC 3339. - `<last-edit-time>`: time the tag was edited, formatted as per RFC 3339.
- `<safety>`: whether the post is safe for work. - `<safety>`: whether the post is safe for work.