DefaultAPISidebar, APIRef and GroupData
In the last couple of weeks I’ve been digging into the DefaultAPISidebar, APIRef and GroupData macros. Having learned some things about them, and developed some opinions on Things We Should Do About It, I thought it would be worth writing it up here, partly to check my understanding, partly to share my understanding, and partly to propose some possible improvements.
This particular post will just describe how AFAICT these things work and what they do. I’ll follow up with replies describing pitfalls and problems, and what we might do about them.
Which sidebar should you use when?
DefaultAPISidebar and APIRef both build sidebars for pages under https://developer.mozilla.org/en-US/docs/Web/API. So which should you use when?
Concepts: APIs and Interfaces
As far as I can see there’s a conceptual distinction in MDN between “APIs” and “Interfaces”. (This is terribly confusing to me because I think of an API as an interface - that’s what the “I” is for.)
An interface is a single concrete type of object that a developer might interact with, like
An API is a more abstract collection of features, that may include multiple interfaces and also individual methods belonging to other interfaces. Generally it seems that APIs align with specifications.
For example. There’s an API we call the Fetch API, that contains all the stuff under the abstract concept of Fetch. This includes specific objects (interfaces) like
Response, but also includes the
fetch() method of the
WindowOrWorkerGlobalScope interface. It has its own spec, that defines all these bits.
Corresponding MDN page types
To document this abstract thing called “Fetch”, we have an overview page whose name is usually (but not always) of the form “APIName_API”. This page gives an overall description of the API. It may also have subpages, which are guides to aspects of the API.
For example: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API, which has child pages like https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Cross-global_fetch_usage.
To document interfaces we have pages whose name is the name of the interface. This page lists the properties, methods, events that are defined for that interface, and these things all get subpages under the interface’s page.
For example, https://developer.mozilla.org/en-US/docs/Web/API/Request describes the
Request interface, and has child pages like https://developer.mozilla.org/en-US/docs/Web/API/Request/method.
Corresponding to this distinction:
API pages (aka landing pages, aka overview pages), and their children should use DefaultAPISidebar.
Interface pages (aka API reference pages), and their children should use APIRef.
What do they do?
GroupData.json is a big blob of JSON. It contains one object for each “group”, where a “group” is basically an API. So there’s an entry called “Fetch API”, one called “WebVR API”, and so on.
Groups may contain:
- the name of an overview page
- names and links to guides about the API
- interfaces, methods, properties, and events that comprise the API
Note that the methods, properties, and events lists do not include items that are under the interfaces: they are for items defined under other interfaces. For example, the entry for “Fetch API” lists
WindowOrWorkerGlobalScope.fetch() but not
APIRef expects to be found on an interface page or the child page of an interface page, like https://developer.mozilla.org/en-US/docs/Web/API/Request or https://developer.mozilla.org/en-US/docs/Web/API/Body/json.
Its content is driven mostly by the pages it finds under that interface page, and their tags. It collects the children of the main interface and sorts them by tag into “constructors”, “methods”, “properties”, “events”, and these links end up in corresponding sections of the sidebar.
It also refers to InterfaceData.json to list other interfaces that this interface implements or inherits from.
It also accepts an argument which is the name of a group, and if this is given, it also uses GroupData.json to fetch interfaces, methods, and properties that belong the given group. These things then get stuffed all together into a “Related pages” bit of the sidebar.
DefaultAPISidebar’s content is mostly driven by GroupData.json. It is given a group name as a parameter. It fetches the named group from GroupData, and from the group adds a link to the overview page, if given, guides, interfaces, properties, methods, events.
Also, if an overview page was listed in the interface, it fetches subpages of that overview, which it adds to the list of guides.
One last macro is ListGroups. This is used in just one page, the root Web/API page. It fetches
GroupData and adds a link to the overview page for each group (i.e. for each API). The link is derived from the overview name, if that exists, or the group’s name. So there’s an implicit assumption here that overview URLs map to overview names or group names: if they don’t, these links will be broken.