mirror of
https://github.com/zkldi/Tachi.git
synced 2026-09-26 17:07:58 +03:00
zk
e363bd2532
* docs: migrate from mkdocs to mdbook - Rename old mkdocs docs/ to old-docs/ for reference - Set up new docs/ with mdbook (book.toml + src/ tree) - Mirror full nav structure from mkdocs.yml into SUMMARY.md - Add Justfile-docs with docs-serve, docs-build, docs-check, docs-install recipes - Import Justfile-docs from root Justfile - Rewrite .github/workflows/docs.yml: build step uses taiki-e/install-action to install mdbook, split into separate build + deploy jobs, PR builds run the check step too * ci(docs): pin actions to SHAs, install mdbook via release binary * ci(docs): install mdbook from apt instead of curling a release binary * dev: replace mkdocs python stack with mdbook in dev image * ci(docs): apt only works on Debian; restore release binary install for Ubuntu CI * docs: fix duplicate file entries in SUMMARY.md * docs: remove docs-install recipe * docs: remove site-url from book.toml to fix asset loading * dev: install mdbook from upstream release binary, not Debian apt The Debian package (0.4.x+ds) strips bundled font assets, leaving the built site without fonts/fonts.css. Use the upstream tarball (same as CI) so the theme is complete. Handles x86_64 and aarch64. * docs: vendor mdbook tarballs in dev/mdbook/, install from there Dockerfile.dev uses COPY + tar to install the right arch at build time. CI extracts the x86_64 tarball directly from the checkout. No network access required for either — and no stripped-fonts Debian package. * fix: unwritten
102 lines
4.4 KiB
Markdown
102 lines
4.4 KiB
Markdown
# API Overview
|
|
|
|
Tachi exposes a public API which allows programs to interact with Tachi.
|
|
|
|
This means you could make your own applications that work off of Tachi's
|
|
datasets.
|
|
|
|
!!! warning
|
|
This documentation assumes some basic programming knowledge, such as how to make
|
|
HTTP requests, and how to parse JSON.
|
|
|
|
Depending on what variant of Tachi you want to interact with, the API is hosted
|
|
on `https://kamai.tachi.ac/api/v1` or `https://boku.tachi.ac/api/v1`.
|
|
|
|
!!! note
|
|
Some API endpoints are only available on Kamaitachi or Bokutachi. If an
|
|
endpoint has this restriction, it will be documented on that endpoints'
|
|
page.
|
|
|
|
---
|
|
|
|
## Abuse
|
|
|
|
The Tachi API is provided under the assumption that it will be used to make
|
|
cool things, and used responsibly.
|
|
|
|
Abuse of this API will result in your ability to use it being banned.
|
|
|
|
The API has a rate limit of 500 requests every minute. This is a very
|
|
generous rate limit, and you should not even be close to hitting it.
|
|
|
|
If you are in a scenario where you might be hitting even 100 requests a minute consistently,
|
|
send an email to `zk@tachi.ac` and let me know what you're up to. Otherwise, I might revoke your tokens for abuse.
|
|
|
|
## License
|
|
|
|
[Tachi-Server](https://github.com/zkldi/Tachi/tree/main/server) (Where the API is written) is licensed under the [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html).
|
|
|
|
To quote GitHub:
|
|
|
|
!!! quote
|
|
Permissions of this strongest copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. When a modified version is used to provide a service over a network, the complete source code of the modified version must be made available.
|
|
|
|
This is not legal advice.
|
|
|
|
## Requests
|
|
|
|
Unless otherwise mentioned, all non-GET request properties should be sent to the API in `application/json` form.
|
|
|
|
GET request properties should be sent to the API in the Query String.
|
|
|
|
Your authentication tokens should be sent in the HTTP `Authorization` header, using `Bearer token` form.
|
|
|
|
You should provide this token for every endpoint. Even though not all endpoints
|
|
require authentication tokens, they are still used for API analytics.
|
|
|
|
## Response
|
|
|
|
Unless otherwise mentioned, all responses to the API are in `application/json` form.
|
|
|
|
The API has two schemas for JSON responses.
|
|
|
|
### Success Response
|
|
|
|
As the name implies, the Success Response is returned on a successful request.
|
|
|
|
| Property | Type | Description |
|
|
| :-----------: | :----------------: | :-------------------------------------------------------------------------------------------: |
|
|
| `success` | true | Always true for a successful response. |
|
|
| `description` | String | Information about what happened with the request. |
|
|
| `body` | Endpoint Dependent | Any data that the endpoint needs to return, such as a user's document from a profile request. |
|
|
|
|
The HTTP Status Code for any Success Response will always be of 2XX form.
|
|
|
|
### Failed Response
|
|
|
|
As the name implies, the Failed Response is returned when a request fails.
|
|
|
|
| Property | Type | Description |
|
|
| :-----------: | :----: | :-------------------------------------------------: |
|
|
| `success` | false | Always false for a failed response. |
|
|
| `description` | String | Information about what went wrong with the request. |
|
|
|
|
The HTTP Status Code for any Failed Response will always be of either 4XX or 5XX form.
|
|
|
|
!!! warning
|
|
The `description` property is **NOT** intended for program usage. You should **NEVER** depend
|
|
on the output of `description`, as it may be changed at any time for any reason.
|
|
|
|
!!! note
|
|
Any API request can fail for any reason. You should always account for the
|
|
case where the request fails.
|
|
|
|
## Footnote
|
|
|
|
That should be everything. If you have any questions about the API, you can
|
|
contact me at `zk@tachi.ac`. You can also write an issue on the
|
|
[Issue Tracker](https://github.com/zkldi/Tachi). I'll get around to either.
|
|
|
|
It's entirely possible that I might've made a typo or wrote a poor explaination
|
|
of something, so please reach out!
|