How should "API pages" represent BCD?

[wbamberg]

We've just recently started supporting BCD queries as front matter keys: mdn/yari#3258. This means the {{Compat}} macro can stop passing it as an argument, and Yari can just automatically add the right BCD table based on the front matter. It also means we can render other data out of the BCD query, too, like specifications tables and maybe soon the "deprecated" banner.

So to take advantage of this we need to move the BCD query string from the {{Compat}} macro call to the front matter. We shouldn't do this for all pages, only pages that are essentially associated with a BCD query. So we shouldn't do it for freeform "guide" pages, even if those guide pages happen to want to show a BCD table.

I've done this more or less for the JS and CSS pages, and started on the WebAPI pages. And then I got a question.

Under Web/API there are several different sorts of pages:

1. Freeform guide pages, like https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch. These are supposed to live under "API pages".

2. API pages - this describes a collection of features, that may include multiple interfaces and also individual methods belonging to other interfaces. Generally it aligns 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 Request and Response , but also includes the fetch() method of the WindowOrWorkerGlobalScope interface. It has its own spec , that defines all these bits.

3. Interface pages: this describes single concrete type of object that a developer might interact with, like Request . These also live at the top level.

4. Method pages: this describes a single method of an interface, like Request.clone(). These live underneath the interface they belong to.

5. Property pages: this describes a single property of an interface, like Request.method. These live underneath the interface they belong to.

6. Dictionary pages: this describes a dictionary in the Web API, which is a lot like an interface that doesn't have any methods. For example, RsaPssParams. These live at the top level alongside interfaces and APIs.

So clearly, guide pages should not get BCD front matter, and interface, method, property, and dictionary pages should get it. But what about API pages? At first I thought they should, because they are reference pages, and we could certainly define a structure for them, and knowing the compat story for an API seems useful. But "APIs" don't map onto a single branch of the BCD tree. So the only way to do it would be for API pages to support more than one BCD query.

At the moment, as usual, it's a bit random.

• some API pages omit BCD: https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API
• some include a single table that only partially describes compat: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
• some include multiple tables: https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API

I think probably they should either omit BCD, and people can refer to the interface pages, or should include multiple tables.

[chrisdavidmills]

@wbamberg this is a good question to ask. In terms of the API landing pages displaying BCD or not, I always thought that it was something that readers would want, but communicated as a quick overview, e.g.

• You can use this entire API in production.
• You can use this bit of the API in production, but not this bit.
• You can't rely on this API in production yet.

They can then dig deeper into the individual interfaces for further info if they still want it.

I thought it would be an annoying faff to say "Look at the interface pages for compatibility information" (although we do this in some places), so wherever possible, I tend to show the compat table for the central most useful feature of the API, or the entry point. It's imperfect, but it does give a quick idea.

In terms of doing it properly, I'm not sure if we should show multiple tables, or some kind of aggregate table?

[jpmedley]

Building on what Chris said, I would imagine that an aggregate table could be constructed using the heuristics in his bullet points. Instead of showing every member of an interface, it could show just the interface name and a signal that indicated one of the three states he lists. We would also generate instructions to visit individual interfaces.

(Aside: It occurs to me that we might have been doing interface support wrong all these years. If I'm looking to use a new interface, I may care more about the version number of the last feature to be supported than the first. I'm not suggesting a change to how the data is stored, but since we've automated table rendering we could think about parsing an interface's children for the highest number and display interface support as a range. If this has been proposed already I'll take my thoughts there. If not and if folks think this is worth discussing, I'll start another issue.)

[ddbeck]

I think probably they should either omit BCD, and people can refer to the interface pages, or should include multiple tables.

As a near-term approach, I suggest we omit the compat tables, but future proof ourselves by allowing an array of BCD strings in the front matter.

This would let us generate spec tables from front matter, which I think would be useful on API pages today (without much real innovation needed, except for de-duplication). It also lets us prepare for a future where pages can show composite compatibility reports or aggregate tables.

[ddbeck]

Partly in response to https://github.com/mdn/content/discussions/4920#discussioncomment-755693, I want to add that, when we choose a course of action here, we ought to be explicit about:

• What we're going to do to content and front matter now (or at least, what we're going to tolerate)
• What we're committing to doing to make that decision work (e.g., removing compat sections or getting the compat macro to accept the first of an array of feature identifiers)
• What we're putting onto the roadmap for the future (e.g., developing aggregate compat tables or summary compat reports)

[jpmedley]

I think probably they should either omit BCD, and people can refer to the interface pages, or should include multiple tables.

I don't agree, and I don't think I even agree with what I said yesterday. Both options put readers through a bunch of yo-yo clicking to get a sense of the entire interface. If you've got the key to generate a table now, why not go ahead and do it, even if it's not perfect? You could incrementally improve a full table. For example, maybe the next step is collapsing the interfaces children with controls to expand one interface at a time and to expand them all.

[wbamberg]

Having thought a bit more, a couple of things:

• a simplistic implementation, where we just show all the BCD tables for all interfaces (&c) in the API would look really bad for big APIs like https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model or https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API. There would just be so many tables. Which suggests that to do this acceptably well would take a solution customized for APIs, where we could summarize the compat story for a given interface in one row (and summarising BCD in this way is much harder than it sounds). Which makes me think that for right now we should not show compat for APIs, and should consider a better implementation further down the road.

• providing BCD for APIs explicitly in the front matter is over-specifying it. We already have a mechanism that describes which interfaces &c constitute an API (GroupData.json). Given that (or some better alternative[1]) we could derive the BCD queries for the features.

• spec tables are an interesting point, and feel like a place where it's unfortunate to have spec urls tied into BCD. APIs do generally map onto a single specification (see also https://discourse.mozilla.org/t/defaultapisidebar-apiref-and-groupdata/40210/5, in the course of which we discussed renaming the sidebar for these things "SpecificationSidebar"). I'm sure there are many places where things are messier, but consider for example Fetch. Here we have an API page: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API that lists a single spec: https://fetch.spec.whatwg.org/. The API includes various interfaces: Request, Response and so on, which each also list the Fetch API spec, but deep-link to the part for that interface: https://fetch.spec.whatwg.org/#request-class. Surely the most sensible thing to do in a case like this is what we are already doing, which means we want the "Fetch API" page to list only https://fetch.spec.whatwg.org/. But does BCD contain an entry for "Fetch API" that would contain a spec URL like https://fetch.spec.whatwg.org/, rather than just deep-links for the concrete interfaces?

[1] I think rather than GroupData we could consider listing the constituents of an API in the front matter for the API page.

[wbamberg]

So I guess one possible future could be:

• have API pages list interfaces &c in front matter, and kill GroupData
• have the piece of Yari that bulids compat tables work differently for API pages. Have it find the BCD queries for the interfaces &c that this API listed in front matter, and build summarized tables that give a high level view
• allow pages to list a spec-url front matter key that overrides BCD (or is only used if browser-compat is omitted, or something), and have API pages use this to provide the top-level link to to spec
• omit browser-compat from API pages

[wbamberg]

Another thing about this that came up in the review of the EyeDropper API: mdn/content#9985. We would like to be able to mark some APIs as experimental. The way to do this is usually to include the {{SeeCompatTable}} macro, which contains a link to a compat table in the page. So currently, if you want to mark an API as experimental, you must include some kind of compat table, or you will get a broken link.

I think the short term fix is probably to remove the link from {{SeeCompatTable}}, or at least to make it optional.

[jpmedley]

I'd go farther than that. If we have the BCD key in the metadata, why not have the page render process read the status from the BCD and do something based on that?

[hamishwillee]

This came up again in https://github.com/mdn/content/issues/33640

I agree with ^^^ that it would be best for the macro to render without a link automatically, though I'd prefer that it did this based on the existence of the heading in the page rather than the frontmatter, since that's the actual target that will be broken.

@caugner What approach is most likely to be acceptable to the yari team in your opinion?

[teoli2003]

The advantage of looking into Frontmatter is that it will work in all cases—even cases we are not considering for the moment. There will never be a broken (or neutralized) link in this header (and it is mostly a test in the macro, with 2 different texts)