11 KiB
Data Standards
- UTF-8 in, UTF-8 out. No exceptions.
- SHA256 for auth_hash. Server will do a basic check to make sure of this.
- Security is not a #1 concern. Basic authorization will be implemented to help prevent users from impersonating each other, but this isn't intended to be bulletproof and you shouldn't trust the system with a password you use elsewhere. All clients should inform the user of this.
- Command-line, on-tilde comes first. Local clients should be possible using SSH port binding, however features like inline images, graphical elements and the like will never be implemented as part of the protocol. Local clients can definitely do things like URL image previews though. Hyperlinks with a different text then the link itself will never be implemented.
Text Entities
The `entities` attribute is an array of objects that represent blocks of text within a post that have special properties. Clients may safely ignore these things without losing too much meaning, but in a rich implementation like an Emacs or GUI, they can provide some highlighting and navigation perks. The array object may be empty. If its not, its populated with arrays representing the modifications to be made.
Objects always have a minimum of 3 attributes: ``` ["quote", 5, 7] ``` object[0] is a string representing the attribute type. They are documented below. The next two items are the indices of the property in the body string. The way clients are to access these indices is beyond the scope of this document; accessing a subsequence varies a lot between programming languages.
Some objects will provide further arguments beyond those 3. They will always be at the end of the array.
| Name | Description |
|---|---|
| `quote` | This is a string that refers to a previous post number. |
| These are formatted like >>5, which means it is a | |
| reference to `post_id` 5. These are not processed in | |
| thread OPs. >>0 may be used to refer to the OP. In | |
| addition to the indices at i[1] and i[2], a fourth value | |
| is provided, which is an integer of the `post_id` being | |
| quoted. Note that the string indices include the >>'s. | |
| `linequote` | This is a line of text, denoted by a newline during |
| composure, representing text that is assumed to be | |
| a quote of someone else. The indices span from the > | |
| until (not including) the newline. | |
| `color` | This is a block of text, denoted by color: body |
| during composure. The body may span across newlines. | |
| A fourth item is provided in the array: it is one of the | |
| following strings representing the color. | |
| `red`, `green`, `yellow`, `blue`, `magenta`, or `cyan`. | |
| `bold` | Like color, except that no additional attribute is |
| `italic` | provided. it is denoted as directive: body during |
| `underline` | composure. |
Threads & Replies
Threads are represented the same when using `thread_index` and `thread_load`, except that the `replies` attribute is only present with `thread_load`. The following attributes are available on the parent object:
| Name | Description |
|---|---|
| `author` | The ID string of the author. |
| `thread_id` | The ID string of the thread. |
| `title` | The title string of the thread. |
| `body` | The body string of the post's text. |
| `entities` | A (possibly empty) array of entity objects for |
| the post `body`. | |
| `tags` | An array of strings representing tags the |
| author gave to the thread at creation. | |
| When empty, it is an array with no elements. | |
| `replies` | An array containing full reply objects in |
| the order they were posted. Your clients | |
| do not need to sort these. Array can be empty. | |
| `reply_count` | An integer representing the number of replies |
| that have been posted in this thread. | |
| `lastmod` | Unix timestamp of when the thread was last |
| posted in, or a message was edited. | |
| `edited` | Boolean of whether the post has been edited. |
| `created` | Unix timestamp of when the post was originally made. |
The following attributes are available on each reply object in `replies`:
| Name | Description |
|---|---|
| `post_id` | An integer of the posts ID; unlike thread and user ids, |
| this is not a uuid but instead is incremental, starting | |
| from 1 as the first reply and going up by one for each | |
| post. These may be referenced by `quote` entities. | |
| `author` | Author ID string |
| `body` | The body string the reply's text. |
| `entities` | A (possibly empty) array of entity objects for |
| the reply `body`. | |
| `lastmod` | Unix timestamp of when the post was last edited, or |
| the same as `created` if it never was. | |
| `edited` | A boolean of whether the post was edited. |
| `created` | Unix timestamp of when the reply was originally posted. |
Errors
Errors are represented in the `error` field of the response. The error field is always present, but is usually false. If its not false, it is an object with the fields `code` and `description`. `code` is an integer representing the type of failure, and `description` is a string describing the problem. `description` is intended for human consumption; in your client code, use the error codes to handle conditions. The `presentable` column indicates whether the `description` should be shown to users verbatim.
| Code | Presentable | Documentation |
|---|---|---|
| 0 | Never, fix | Malformed json input. `description` is the error |
| your client | string thrown by the server-side json decoder. | |
| 1 | Not a good | Internal server error. Unaltered exception text |
| idea, the | is returned as `description`. This shouldn't | |
| exceptions | happen, and if it does, make a bug report. | |
| are not | clients should not attempt to intelligently | |
| helpful | recover from any errors of this class. | |
| 2 | Nadda. | Unknown `method` was requested. |
| 3 | Fix. Your. | Missing, malformed, or otherwise incorrect |
| Client. | parameters or values for the requested `method`. | |
| This is returned, for example, when a request to | ||
| `edit_post` tries to edit a post_id that does | ||
| not exist. Its also used to indicate a lack of | ||
| required arguments for a method. This is a generic | ||
| error class that can cover programming errors | ||
| but never user errors. | ||
| 4 | Only during | Invalid or unprovided `user`. |
| registration | ||
| During registration, this code is returned with a | ||
| `description` that should be shown to the user. | ||
| It could indicate an invalid name input, an | ||
| occupied username, invalid/missing `auth_hash`, | ||
| etc. | ||
| 5 | Always | `user` is not registered. |
| 6 | Always | User `auth_hash` failed or was not provided. |
| 7 | Always | Requested thread does not exist. |
| 8 | Always | Requested thread does not allow posts. |
| 9 | Always | Message edit failed; there is a 24hr limit for |
| editing posts. | ||
| 10 | Always | User action requires `admin` privilege. |
| 11 | Always | Invalid formatting directives in text submission. |