From 3f084e6a5b042dd3eaad7c1231ada5c2f8d0f5d6 Mon Sep 17 00:00:00 2001
From: Hamish Willee <hamishwillee@gmail.com>
Date: Fri, 13 Oct 2023 15:16:28 +1100
Subject: [PATCH] Improve Web API overview

---
 files/en-us/web/api/web_authentication_api/index.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/files/en-us/web/api/web_authentication_api/index.md b/files/en-us/web/api/web_authentication_api/index.md
index fd2e2401fe546e0..c18b5723f584e42 100644
--- a/files/en-us/web/api/web_authentication_api/index.md
+++ b/files/en-us/web/api/web_authentication_api/index.md
@@ -36,9 +36,9 @@ To illustrate how the credential creation process works, let's describe the typi
 
 1. The relying party server sends user and relying party information to the web app handling the registration process, along with the "challenge", using an appropriate secure mechanism (for example [Fetch](/en-US/docs/Web/API/Fetch_API) or [XMLHttpRequest](/en-US/docs/Web/API/XMLHttpRequest)).
 
-   > **Note:** The data exchange format is also at the developer discretion.
-   > If you want to use JSON, the {{domxref("PublicKeyCredential.parseCreationOptionsFromJSON_static", "PublicKeyCredential.parseCreationOptionsFromJSON()")}} static method is provided as a convenience method for deserializing a JSON representation of the credential options, which you can then pass to `create()` in the next step.
-   > Similarly {{domxref("PublicKeyCredential.parseRequestOptionsFromJSON_static", "PublicKeyCredential.parseRequestOptionsFromJSON()")}} can convert serve-sent options for [authenticating a (registered) user](#authenticating_a_user) and [JSON.stringify()](/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) can serialize credential objects (via {{domxref("PublicKeyCredential.toJSON()")}}) for sending back to the server.
+   > **Note:** The format for sharing information between the relying party server and the web app is up to the application.
+   > A recommended approach is to exchange {{glossary("JSON type representation")}} objects for credentials and credential options.
+   > Convenience methods hae been created in `PublicKeyCredential` for converting from the JSON representations to the form required by the authentication APIs: {{domxref("PublicKeyCredential.parseCreationOptionsFromJSON_static", "parseCreationOptionsFromJSON()")}}, {{domxref("PublicKeyCredential.parseRequestOptionsFromJSON_static", "parseRequestOptionsFromJSON()")}} and {{domxref("PublicKeyCredential.toJSON()")}}.
 
 2. The web app initiates generation of a new credential via the authenticator, on behalf of the relying party, via a {{domxref("CredentialsContainer.create()", "navigator.credentials.create()")}} call. This call is passed a `publicKey` option specifying device capabilities, e.g., whether the device provides its own user authentication (for example with biometrics).