APIs should allow introspection

[LeaVerou]

This was brought up in w3ctag/design-reviews#619

Namely, that it is too high effort for developers to slightly modify the default config, because it was not exposed anywhere and they would have to recreate it.

But this is a general point. The Web Platform has a history of APIs that are insufficiently introspective, causing developer pain and needless library bloat. It is common for Web APIs to keep large complex objects hidden and use them internally, without exposing them to developers. When developers need them, they need to re-create them manually.

Some examples:

• No way to get all supported events (some are exposed via on* attributes but not all)
• No way to get all supported element types (iterating over HTML*Element helps some, but doesn't even get you that close)
• The CSS OM is a repeat offender (and Typed OM does not fully address these issues): no way to easily get a list of all supported properties, @-rules, media features, color keywords, etc.
• Intl: No way to get all supported currencies, time zones, locales, month names, week names

(I will edit this post to add more examples as I remember them — pretty sure there are many more as I kept hitting this issue as a developer)

[kenchris]

I think it should be clear that this is for introspecting APIs, like available events (that is API) instead of available cameras (not API, but external resource/device)

[LeaVerou]

Summary from breakout:

• Generally yes, but fingerprinting concerns need to be considered before exposing these data structures. A supported list of e.g. timezones may potentially expose more granular information than browser & OS version.
• @LeaVerou to work on text

[torgo]

We discussed the need or a negative example - one that is either too expensive or exposes info that can be used for fingerprinting.

[LeaVerou]

Another example: No way to get event constructor from event type (e.g. MouseEvent from "click") so that the correct constructor can be used for synthetic events where the type is variable. Instead, the code needs to maintain the mapping of event types to constructors, which is bound to get out of date very fast.

[annevk]

The more you expose these kind of things the harder changes might become as well. And for some of them there's indeed many questions one might ask. "Does the UA support onclick?" "Does the UA fire click?" "Does the UA fire click on this event target?" "What interface does the UA use for click for this event target?" (I'm pretty sure a general mapping is wrong and we use different event classes depending on the event target, e.g., load events on XMLHttpRequest come to mind.)

We've had discussions about element names and classes too, but that too is tricky as we might want to change classes over time, etc.

So while this can be useful, actually exposing it in a way that is sound is its own exercise that requires use cases and requirements and a solid understanding of the problem space, which is why I don't think it makes sense to require this upfront from all APIs.