The Voshi API

Your tool never builds a URL, sends a token, or calls fetch(). Everything it needs from Voshi is on one object, api, which Voshi constructs from the launch and passes to your element.

class MyTool extends HTMLElement {
    constructor(api) {
        super()
        this.api = api
        this.attachShadow({ mode: 'open' })
    }

    async connectedCallback() {
        this.shadowRoot.replaceChildren(await this.api.assets.getTemplate('index.html'))
        try {
            const saved = await this.api.storage.memberLocation.get()
            this.render(saved)
        } catch (err) {
            this.showError(err.message)
        }
    }
}

customElements.define('my-tool', MyTool)

What is on it

	What	Page
api.user, api.isStaff, api.isStudent, api.groups	Who launched, and their role in the course	Who launched
api.location, api.course, api.organization	Which of your locations, in which course, at which school	Who launched
api.canSubmitGrade	Whether this launch has a gradebook column	Grades
api.submitGrade(...)	Report a score	Grades
api.storage.course, .location, .member, .memberLocation	Four JSON objects your tool owns, each with get, set, update, patch	Storage
api.storage.<scope>.files	Files kept beside each of those, with list, info, get, put, remove	Files
api.assets	Your tool's own files: templates, stylesheets, data, and the URL of any of them	Assets
api.launch_data	The whole launch, for anything the properties above don't cover	Who launched

Three habits

Every call that reaches Voshi is async. await it. Reading storage, saving, reporting a grade, listing files — all of them return promises.

Every call throws on failure. A method never returns an error object or a status code; if something went wrong, it throws, and err.message says what. So wrap calls in try/catch and tell the learner what happened. See Errors for the kinds of error and what each means.

Check before you act. api.canSubmitGrade before submitGrade(); api.isStaff before showing instructor features or writing the shared rows. The checks are properties, not calls, and they are correct for this launch.

Versions of the client

The client is versioned like any package, major.minor.patch: published to npm as voshi-api, and served as a file per release, such as voshi-api.1.0.0.js. Breaking changes move to a new major. A hosted tool is handed the newest release of its major, so it receives minor and patch updates without doing anything; those arrive rarely and between semesters. A tool with its own server pins the version it installed or downloaded. The Python client on PyPI (also voshi-api) mirrors the JavaScript one and shares its major and minor, so 1.2.x there is 1.2 here. Everything in these pages is version 1.