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(this.api.assets.template('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 stylesheets, templates, and file URLs	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 Voshi API is a file Voshi serves alongside your tool, and it has a major version — the 1 in voshi-api.1.js. Breaking changes move to a new number; within a number, updates arrive rarely and between semesters, and your tool receives them without doing anything. Everything in these pages is version 1.