Guides

API: overview

What the site publishes as JSON, how to read it, what is promised to stay the same and how to call it from any language.

The documentation of a plugin should not copy what a button, a table or a colour is: it should point here. Everything this site knows is published as static JSON, so any other documentation, build script, test or editor can read it. This page is the map; the other pages of the guide go deep into each part.

What you get

You want to…	Read	Page of the guide
Know what exists and open a page in a given state	`/api/index.json`	Overview, Links and states
List every page and read its text	`/api/index.json`, `/api/pages/<id>.json`	Pages and search
Copy the markup of a component	`/api/components/<component>.json`	Components and examples
Read the CSS variables of a Moodle version	`/api/tokens/<version>.json`	Tokens and versions
Draw a Moodle icon with Font Awesome	`/api/icons.json`	Icons and brand
Use the colours and the logo of Didactika	`/api/brand.json`	Icons and brand
Check the shape of every file		Reference of the files

The address

GET https://moodle-design.didactika.org/api/index.json

The site is served by GitHub Pages: there is no key, no login and no rate you have to manage. Every response is a JSON file with Content-Type: application/json and the header Access-Control-Allow-Origin: *, so it can also be read from a browser on any other site.

The entry point

/api/index.json holds, in one file:

Field	What it is
`schema`	The version of the shape of the JSON (see below)
`name`, `site`, `repository`, `licence`	What this is and where it lives
`languages`	`["en", "es"]`
`designSystem`, `theme`	The versions of the design system and of the Didactika theme, with the default of each
`versions[]`	Each Moodle version with its Bootstrap generation, icon family, support and the links to its `tokens` and `stylesheet`
`resources`	The addresses of the components, the icons and the brand
`pages[]`	Every page: identifier, group, order, section, versions, title, summary, addresses and the examples it uses
`deepLinks`	How a page opens in a given state

const root = 'https://moodle-design.didactika.org';
const index = await (await fetch(root + '/api/index.json')).json();

if (index.schema !== 1) { throw new Error('Unknown schema: ' + index.schema); }
console.log(index.designSystem.default, index.theme.default);   // "0.1" "0.1"
console.log(index.versions.map((v) => v.label));                 // ["Moodle 5.3 LTS", ...]

Stable on purpose

Every file carries "schema": 1. The number changes only when a field is removed or changes meaning. Adding fields never changes it, so a reader that checks the number and ignores what it does not know keeps working when the site grows.
The identifiers of pages (bootstrap/buttons) and of examples (buttons/icons) do not change once published. Titles and summaries may.
A removed example or page disappears from the lists; its old address stops answering.
The data is rebuilt with the site. Cache it for a day, not forever, and never for longer than the version of the design system you target.

Calling it from other languages

curl -s https://moodle-design.didactika.org/api/index.json | jq '.pages[] | select(.group == "patterns") | .id'

$root = 'https://moodle-design.didactika.org';
$index = json_decode(file_get_contents($root . '/api/index.json'), true);
foreach ($index['pages'] as $page) {
    echo $page['id'] . ' - ' . $page['title']['en'] . PHP_EOL;
}

import json, urllib.request

root = "https://moodle-design.didactika.org"
with urllib.request.urlopen(root + "/api/components/buttons.json") as response:
    buttons = json.load(response)
print([e["id"] for e in buttons["examples"]])

Good manners

Download once in your build, not on every page view of your documentation.
Check schema before you read and ignore unknown fields.
Keep the licence: the site and its data are GPL-3.0-or-later.