mirror of
https://github.com/zkldi/Tachi.git
synced 2026-10-07 22:38:02 +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
124 lines
3.6 KiB
Markdown
124 lines
3.6 KiB
Markdown
# Import Document Endpoints
|
|
|
|
!!! note
|
|
This should not be confused with [Import Endpoints](./import.md). Those are for
|
|
importing scores, whereas these endpoints are for Import Document interaction.
|
|
|
|
*****
|
|
|
|
*****
|
|
|
|
## Retrieve an import document and information about it.
|
|
|
|
`GET /api/v1/imports/:importID`
|
|
|
|
### Parameters
|
|
|
|
None.
|
|
|
|
### Response
|
|
|
|
| Property | Type | Description |
|
|
| :: | :: | :: |
|
|
| `scores` | Array<ScoreDocument> | All of the scores imported from this import. |
|
|
| `songs` | Array<SongDocument> | All of the songs related to the scores in this import. |
|
|
| `charts` | Array<ChartDocument> | All of the charts related to the scores in this import. |
|
|
| `sessions` | Array<SessionDocument> | All of the sessions created as a result of this import. **Note that this does not include sessions modified by this import!** |
|
|
| `import` | ImportDocument | The Import document you requested. |
|
|
| `user` | UserDocument | The user document for the person who made this import. |
|
|
|
|
*****
|
|
|
|
## Revert an import.
|
|
|
|
`POST /api/v1/imports/:importID/revert`
|
|
|
|
!!! info
|
|
This endpoint is intended to *undo* a faulty import. For example, if you were using
|
|
a batch-manual script that somehow went haywire. Normal users should *not* need to
|
|
use this, but it is on the UI regardless incase they cause catastrophic failure.
|
|
|
|
!!! warning
|
|
Reverting an import is equivalent to undoing all of the scores that were imported as
|
|
a result of the import. This, however, does not necessitate that classes will be
|
|
reverted, such as if the import also declared you as kaiden -- that currently requires
|
|
manual moderator intervention.
|
|
|
|
### Permissions
|
|
|
|
- delete_score
|
|
- Must be the owner of this import (Or a server administrator).
|
|
|
|
### Parameters
|
|
|
|
None.
|
|
|
|
### Response
|
|
|
|
None. (Empty Object)
|
|
|
|
*****
|
|
|
|
## Poll an ongoing import
|
|
|
|
`GET /api/v1/imports/:importID/poll-status`
|
|
|
|
!!! question
|
|
The reason we can't directly respond with import info is that `tachi-server` **may**
|
|
use a feature called SCORE_IMPORT_WORKERS. This dedicates score processing to separate
|
|
processes which communicate back with any parent server. This means that the result of
|
|
an import processed on one server may be returned by another.
|
|
|
|
This feature is enabled on our instances of `tachi-server` -- Boku and Kamai, which
|
|
means you will have to poll this endpoint.
|
|
|
|
!!! info
|
|
You are intended to poll this endpoint every one second or so. Do it until
|
|
`body.importStatus` is "completed".
|
|
|
|
!!! tip
|
|
`body.progress.description` is human-friendly output, you can render it to
|
|
a client on every ping in the case where `body.importStatus` is "ongoing".
|
|
|
|
### Parameters
|
|
|
|
None.
|
|
|
|
### Response
|
|
|
|
| Property | Type | Description |
|
|
| :: | :: | :: |
|
|
| `importStatus` | "completed" \| "ongoing" | If this is equal to completed, the import is finished and the importDocument is returned under `import` . If this is "ongoing", a `progress` key will display information and progress though the import |
|
|
| `progress` | `{ description: string }` \| Not Present | If `importStatus` is "ongoing", this will contain a string `description` of where in the import process this import is. |
|
|
| `import` | ImportDocument \| Not Present | If `importStatus` is "completed", this will contain the import document that was just inserted into the database. |
|
|
|
|
### Example
|
|
|
|
#### Request
|
|
```
|
|
GET /api/v1/imports/my_import_id/poll-status
|
|
```
|
|
|
|
#### Response
|
|
|
|
```js
|
|
{
|
|
importStatus: "ongoing",
|
|
progress: {
|
|
description: "Imported 1832 Scores..."
|
|
}
|
|
}
|
|
```
|
|
|
|
Alternatively,
|
|
|
|
```js
|
|
{
|
|
importStatus: "completed",
|
|
import: {
|
|
importID: "my_import_id",
|
|
scoreIDs: ["foo", "bar"],
|
|
// ... more import props
|
|
}
|
|
}
|
|
``` |