Bug 20128 - clarify structure for API members that supplement core DOM interfaces
Summary: clarify structure for API members that supplement core DOM interfaces
Alias: None
Product: webplatform.org
Classification: Unclassified
Component: info architecture (show other bugs)
Version: unspecified
Hardware: PC All
: P2 normal
Target Milestone: ---
Assignee: Doug Schepers
QA Contact: public-webplatform-bugs list
Depends on:
Reported: 2012-11-28 18:59 UTC by Mike Sierra
Modified: 2013-03-14 17:18 UTC (History)
2 users (show)

See Also:


Note You need to log in before you can comment on or make changes to this bug.
Description Mike Sierra 2012-11-28 18:59:53 UTC
Part architecture, part infrastructure. Bug relates to a topic in
11/18 site-content conf-call & earlier unresolved discussion in
"URL structure sanity check" public email thread.  Here's the
canonical URL structure for non-core APIs:


Good for new interfaces, but API packages often add members to core
interfaces (e.g. Document, Window, Navigator). Two examples:

* DeviceOrientation API adds a few events to the Window object. It
  does not add any new API interfaces.

* CSS Regions API (apis/css-regions) adds 'getNamedFlows' member to
  the Document interface. It's common to add such members simply to
  access specialized APIs.  (In this case, I placed it here:

Question: should these members be added to /dom tree, or supplement
the existing /apis URL structure? E.g.:


Arguments in favor of the latter:

* Placing them directly on /dom interface page would otherwise list
  core members & more specialized members all jumbled together, and
  the distinction is info webdevs might find useful when viewing each
  /dom page.

* Maybe there's an opportunity to use templates to import
  supplementary members from /api to populate appropriate /dom
  interface. Page could be separated into core & non-core members.

* There's a benefit to being able to scan each /apis/<package> page
  and be able to view all relevant members from any interface,
  analogous to the everything-you-need-to-know structure of W3C specs.

* Relates to bug #20103: would like <package> pages to generate nested
  list allowing users to drill down directly to any member.

One caveat:

* What if users land on /apis/<package>/Document page? We're not going to
  re-doc it. Is a redirect to appropriate location under /dom possible?
Comment 1 Chris Mills 2012-11-29 08:39:11 UTC
This makes sense to me Mike. I suggest we go with this, if there are no dissenters. Update the hierarchy information at http://docs.webplatform.org/wiki/WPD:Content/Topic_Hierarchy ?
Comment 2 Mike Sierra 2012-11-29 20:05:35 UTC
OK, as a test case I moved
& kept the interface name Initcap to stay consistent with rest of

Ideally at some point, dom/apis/document should dynamically list
getNamedFlows, perhaps in a separate list of supplementary members.

Also ideally, the new interim apis/css-regions/Document page should
redirect to dom/apis/document, or else dynamically reflect its content.  
Requiring it to be created by hand would invite	fragmented out-of-context
Comment 3 Chris Mills 2012-11-30 10:21:00 UTC
Sounds good, but shouldn't we be using all lower case for URLs, like we agreed a while ago?
Comment 4 Mike Sierra 2012-11-30 17:05:07 UTC
Think this needs clarification. From discussion over the /apis tree I took away this convention:

Comment 5 Jonathan Garbee 2013-03-14 17:18:14 UTC
New location: http://project.webplatform.org/ia/issues/9