Consider merging Credential Management-related specifications?

[wbamberg]

I'm doing some work on the Credential Management API and had a suggestion.

The CM API provides a kind of framework that several other specifications plug into:

• Web Authentication API
• WebOTP API
• Federated Credential Management API

Usually our practice on MDN is to document separate specifications separately, and that's what we've done here.

But in some cases, including arguably this one, it can lead to fragmentary docs in which it's hard for readers to get an overview of what's going on. For example:

• the core create() and get() methods are defined in the CM API, so their sidebars list the objects defined in the CM API. These methods return a subclass of Credential, but most of those subclasses are not listed in the sidebar, because they're defined in different specs.
• the documentation for methods like create and get would like to talk about all the credential types (e.g. WebOTP codes, WebAuth assertions, etc) that can be used with them, but is then straying into documentation belonging to the other specifications.
• conversely, the documentation for an API like WebOTP wants to talk about using create and get, but those belong in the CM API tree. The documentation for https://developer.mozilla.org/en-US/docs/Web/API/WebOTP_API looks pretty stunted and a little incoherent because it's missing the context provided by the CM API docs.
• the fact that these credentials are defined in different specs seems to be a matter of how the spec authors have organized themselves, rather than any technical feature that web developers need to care about. Why should a web dev care that WebOTP is defined in a different spec from CM API?

So we could consider instead folding all the other specs into the CM API documentation. The obvious precedent for this is the Performance documentation, where there are many tiny specs that extend the core Performance stuff, and that we all rolled up together last year when @Elchi3 did the rewrite.

[hamishwillee]

I don't have a problem with mixing interfaces if it helps, but I am not certain it is a silver bullet.

If you mix all the APIs there are lots of irrelevant interfaces for each of the current APIs and you still only get Navigator.credentials at the top level. Is having a sea of interfaces better or worse than "missing" parts of the APIs in the sidebar?

The big problem here is I don't see how we can do this "right" - except perhaps with some infrastucture that allows "sub APIs" so we could display all three APIs in the sidebar at the same time as separate APIs.

Can we prototype just dumping everything in one "Authentication API" and seeing how navigable it is to do it this way?

---

Notes:

• OTP uses get() but not create() AFAIK.
• It gates on https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy/otp-credentials so we should minimally add that to the CM get() docs if it isn't there.

[wbamberg]

I'm not exactly advocating for this, and I'm not sure it's the right thing to do, but ...

If you mix all the APIs there are lots of irrelevant interfaces for each of the current APIs and you still only get Navigator.credentials at the top level. Is having a sea of interfaces better or worse than "missing" parts of the APIs in the sidebar?

A "sea of interfaces" seems like a bit of a loaded expression for not that many interfaces - if you amalgamate the four APIs you get 15 interfaces which is a very small sea, more of a large puddle. What you do get though, is all the credential types appearing together in a single list, which helps reinforce the core idea that the CM API works with a variety of different credential types.

Look at the sidebar for WebOTP:

It has only two items in it. The key one is CredentialsContainer.get(). If I click that, I get a totally different sidebar, with no link to OTPCredential any more. This seems like a bad nav experience.

I do, however, see links to PasswordCredential and FederatedCredential. Why? What's the user-centric rationale for linking to these credential types and not OTPCredential or IdentityCredential? There's none, except that those types were defined in a different spec.

The big problem here is I don't see how we can do this "right" - except perhaps with some infrastucture that allows "sub APIs" so we could display all three APIs in the sidebar at the same time as separate APIs.

I'm not sure how that helps though. Who cares about "APIs", where "API" really means "spec"? Why does it matter to any web developer that FedCM is a different spec from CM?

There are absolutely irreducible problems with these APIs, mainly things like "don't use the thing called FederatedCredential for federated credentials, use the thing called IdentityCredential" but it might be easier to explain these if we unify the types.

Can we prototype just dumping everything in one "Authentication API" and seeing how navigable it is to do it this way?

Combining CM, WebAuthn, WebOTP, and FedCM would get a sidebar that looks like this:

I would add a couple of overview guides and try to homogenise the names of the existing guides, to present it as a unified whole.

OTP uses get() but not create() AFAIK.

Yes, same for FedCM. Similarly only PasswordCredential and (maybe?) FederatedCredential use store().

[hamishwillee]

FWIW I think that is a bit of a "sea of interfaces" if you're only interested in OTP. But you're mis-interpreting me - it was a genuine question "is this better?" I did the same experiment with looking at OTP and navigating too and that is rubbish.

On balance I think it is better. BTW, would be nice to spell out OTP at least once as "one time password".

It is a bit annoying that you lose guides if you go to an interface. If I was looking at one of these docs to work out what are the relevant interfaces for what I want to do, it would be good to easily be able to go back to the "relevant list". That's what the sidebar is supposed to do for you, and if you have just one related feature set it does.

[wbamberg]

It is a bit annoying that you lose guides if you go to an interface.

Very annoying, indeed -> mdn/yari#6229.

[chrisdavidmills]

Having read through this discussion, I will start by saying that I appreciate the effort here in trying to improve this situation. I tried documenting FedCM, and WebOTP, and making improvements to WebAuthn, using the normal strategy we tend to use in documenting APIs. But it didn't work particularly well because of the weird footprint of these APIs.

A few thoughts:

1. I really like the idea of using the Performance APIs work as a model for this. I suppose in this case, the API landing page would be something similarly generic, such as "Authentication API". I think that would be OK, as all of the subparts are relevant to Authentication.
2. I don't see the "puddle" of interfaces as such as huge problem, provided they are gathered together under a single sidebar
3. The new API landing page should do a nice concise job of mapping out the high-level landscape of all of the authentication-related APIs and explaining what use cases they solve for. Perhaps you could move some of the deeper explanations to guide pages instead, to avoid the landing page becoming too bloated.
4. I'd recommend naming the guides so that they relate really cleanly to the use cases rather than the APIs, and sit in a useful order for navigating those use cases. So for example:
   a. the WebOTP landing page and any related stuff on get() could become a guide called "Using one-time passcodes".
   b. the FedCM "Identity provider integration with FedCM" and "Relying party federated sign-in" guides could become "Federated Credentials: Identity provider integration" and "Federated Credentials: Signing in users" or somesuchthing
5. get() and create() are a bit of a mess. Would you look to break them up into multiple pages covering the dictionaries relevant to each API?

[wbamberg]

Thanks @hamishwillee and @chrisdavidmills for your thoughts both, they are greatly appreciated. I agree with just about everything Chris has in https://github.com/orgs/mdn/discussions/683#discussioncomment-9517279.

I'm going to do this piecemeal, trying to improve what's already there before trying to move things around.

I think "Authentication API" makes sense? Names are hard :).

So next up I think is:

• write some overview/orientation stuff on the various credential types. I had thought of making this a separate guide but now think it might fit better in the current CM API landing page (possible future Auth API landing page). We'll see.

• fix up get() in the same way as Normalize CredentialsContainer.create() method content#33360

Then after that consider amalgamating the APIs, and writing/reshaping various guide pages.

[hamishwillee]

Yes, that all works for me :-). I'd do get() first, on the basis that it's the greatest bang-for-buck. Authentication API also works for me. We can add a note that the parts of the APIs are in different specifications if we are worried about people getting confused.

[chrisdavidmills]

Sounds perfect Will.

[Rumyra]

Sorry for just getting around to reading this - I also agree with what @chrisdavidmills says :)

If we separate this into two problems: 1. sidebars reflecting related docs & 2. organising docs to make sense I see a future where

1. We're working on bettering sidebar authoring over the next 6 months which should help
2. I'm beginning to wonder whether in the long term web-features grouping could help us make decisions in cases such as these

[wbamberg]

Thanks @hamishwillee and @chrisdavidmills for your thoughts both, they are greatly appreciated. I agree with just about everything Chris has in https://github.com/orgs/mdn/discussions/683#discussioncomment-9517279.

I'm going to do this piecemeal, trying to improve what's already there before trying to move things around.

I think "Authentication API" makes sense? Names are hard :).

So next up I think is:

• write some overview/orientation stuff on the various credential types. I had thought of making this a separate guide but now think it might fit better in the current CM API landing page (possible future Auth API landing page). We'll see.

Done in mdn/content#33745.

• fix up get() in the same way as Normalize CredentialsContainer.create() method content#33360

Done in mdn/content#35255.

Then after that consider amalgamating the APIs, and writing/reshaping various guide pages.