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
3.6 KiB
Import Document Endpoints
!!! note This should not be confused with Import Endpoints. 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
{
importStatus: "ongoing",
progress: {
description: "Imported 1832 Scores..."
}
}
Alternatively,
{
importStatus: "completed",
import: {
importID: "my_import_id",
scoreIDs: ["foo", "bar"],
// ... more import props
}
}