20128 2012-11-28 18:59:53 +0000 clarify structure for API members that supplement core DOM interfaces 2013-03-14 17:18:14 +0000 1 1 1 Unclassified webplatform.org info architecture unspecified PC All RESOLVED MOVED P2 normal --- 1 letmespellitoutforyou schepers cmills jonathan public-webplatform-bugs oldest_to_newest 79029 0 letmespellitoutforyou 2012-11-28 18:59:53 +0000 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: /apis/<package>/<interface>/<member> 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: /dom/apis/document/getNamedFlows) Question: should these members be added to /dom tree, or supplement the existing /apis URL structure? E.g.: /apis/<package>/Document/<member> /apis/<package>/Window/<member> /apis/<package>/Navigator/<member> 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? 79096 1 cmills 2012-11-29 08:39:11 +0000 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 ? 79151 2 letmespellitoutforyou 2012-11-29 20:05:35 +0000 OK, as a test case I moved dom/apis/document/getNamedFlows to apis/css-regions/Document/getNamedFlows & kept the interface name Initcap to stay consistent with rest of apis/. 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 content. 79173 3 cmills 2012-11-30 10:21:00 +0000 Sounds good, but shouldn't we be using all lower case for URLs, like we agreed a while ago? 79196 4 letmespellitoutforyou 2012-11-30 17:05:07 +0000 Think this needs clarification. From discussion over the /apis tree I took away this convention: /apis/<api_bundle>/<InterfaceName>/<memberInCamelCaseWhereApplicable> 84432 5 jonathan 2013-03-14 17:18:14 +0000 New location: http://project.webplatform.org/ia/issues/9