Adding new API - whether to use namespaces

[Jiewei Qian]

Hi blink-dev,

We are designing a new API for handwriting recognition, and want to know if we should put methods behind a namespace.

We have two methods:

• navigator.queryHandwritingRecognizerSupport
• navigator.createHandwritingRecognizer

We anticipate most websites will call the first method (to decide if the handwriting recognition support meets their needs), before calling the second (to make use of the feature).

We want to know if it's more preferable to put them behind a namespace, for example:

• navigator.handwriting.queryRecognizerSupport
• navigator.handwriting.createRecognizer

[Thomas Steiner]

As the co-author of the article about the feature I find the namespaced variant more logical and more in-line with how other APIs work, for example, Geolocation. (Not a big argument: It also allows for better minification.) 

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CANFkJJ%3DdX_DHHo2fSNJPL1DT5zGnuQYKGfjeHekrbcRE4E%2Bo6w%40mail.gmail.com.

--

Thomas Steiner, PhD—Developer Advocate (https://blog.tomayac.com, https://twitter.com/tomayac)

Google Germany GmbH, ABC-Str. 19, 20354 Hamburg, Germany
Geschäftsführer: Paul Manicle, Halimah DeLaine Prado
Registergericht und -nummer: Hamburg, HRB 86891

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.1.23 (GNU/Linux)

iFy0uwAntT0bE3xtRa5AfeCheCkthAtTh3reSabiGbl0ck0fjumBl3DCharaCTersAttH3b0ttom.hTtPs://xKcd.cOm/1181/
-----END PGP SIGNATURE-----

[Yuki Shiino]

Just as an input, Web IDL supports "namespace", which is different from a namespace-ish object.

Example)

https://drafts.csswg.org/cssom/#the-css.escape()-method

CSS namespace appears as "window.CSS" in JavaScript.

"window.navigator" is a (singleton) instance of Navigator interface (hence the object can be stateful) and not a namespace (which is stateless).

It's a convention that Web IDL namespace's name starts with an uppercase (window.CSS) while Web IDL attribute's name starts with a lowercase (window.navigator).  Web IDL namespaces are exposed on global objects (like "window.CSS").

Cheers,

Yuki Shiino

2021年8月24日(火) 15:40 'Thomas Steiner' via blink-dev <blin...@chromium.org>:

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CALgRrLm16Bhv88nz4Yts999890b4kbDdKmGJVcJxCiSVYtY%3DsQ%40mail.gmail.com.

[Domenic Denicola]

I would suggest *not* doubly-nesting. I.e. handwriting.queryRecognizerSupport, not navigator.handwriting.queryRecognizerSupport.

And, using a proper namespace might indeed be best here.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAN0uC_S901%2BzrvHC_wuQKqMSmvcC%3DSX9xijweyr8X_NhW%2BJj-g%40mail.gmail.com.

[Jiewei Qian]

Thanks for the feedback. I should have been more clear with the terminology. 

Seems navigator.handwriting.{create, query}Recognizer is preferred.

Other APIs also use this pattern (e.g. navigator.usb, navigator.bluetooth, navigator.geolocation).

> Web IDL namespaces

Thanks for Yuki's explanation. Our API can change states (e.g. it needs to create a recognizer in the browser), so Web IDL namespace isn't a good fit.

> Double nesting

I'm a bit hesitant about adding a new global / window scoped object, as it could interfere with existing code (e.g. when JS defines a global handwriting variable by itself). Putting it behind the navigator object is more robust.

Also, handwriting recognition capability is provided (and varies) by the browser, so it would make sense to put it on the navigator object.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAM0wra_DJ267NhiZVRW3xjVCYotxQQ2rXF4s%3DZQc8TZ8tQy5fw%40mail.gmail.com.

[Yuki Shiino]

Domenic is a true expert of web specs, and I'd recommend hearing his thoughts more.

Seems navigator.handwriting.{create, query}Recognizer is preferred.
Other APIs also use this pattern (e.g. navigator.usb, navigator.bluetooth, navigator.geolocation).

It's not always true that "other APIs" are doing the best practice.  Also, the web has a long history, so some APIs use really old conventions.  Maybe we'd need a closer look to make a better decision.

Our API can change states (e.g. it needs to create a recognizer in the browser), so Web IDL namespace isn't a good fit.

The first option (IMHO) would be to let web authors create an instance in the case that the objects should be stateful.  Singleton pattern has its own caveats, and is not always recommended (I'd generally recommend avoiding the singleton pattern if possible).  Maybe you have good reasons to choose the singleton pattern, but it's not clear in this thread.

> Double nesting
I'm a bit hesitant about adding a new global / window scoped object, as it could interfere with existing code (e.g. when JS defines a global handwriting variable by itself). Putting it behind the navigator object is more robust.
Also, handwriting recognition capability is provided (and varies) by the browser, so it would make sense to put it on the navigator object.

This is a reason why IDL interface/namespace objects are exposed as {configurable: true, writable: true}.  Web authors' JavaScript code can overwrite/re-define the symbol so that the conflict doesn't happen.  For IDL attributes, [Replaceable] extended attribute exists for this purpose.

I'm afraid that we don't yet have enough information on this thread about restrictions, circumstances, etc. of the web APIs to make the best decision.

Cheers,

Yuki Shiino

2021年8月25日(水) 15:34 Jiewei Qian <q...@chromium.org>:

[Domenic Denicola]

Thanks Yuki; you said everything I was going to say :). I'll just second that you should really avoid double nesting; it's unfortunate other APIs have done so, but we're trying to move away from that.