$varName, hints, tips, links

microsoft-edge/extensions-chromium/publish/api/addons-api-reference.md

@@ -23,9 +23,12 @@ As of September 6, 2024, both v1.1 and v1 of this Update REST API are supported.
 
 <!-- ====================================================================== -->
 ## Upload a package to update an existing submission
+<!-- endpoint 1: POST /submissions/draft/package -->
 
 Uploads a package to update an existing draft submission of an add-on product.
 
+See also [Uploading a package to update an existing submission](./using-addons-api.md#uploading-a-package-to-update-an-existing-submission) in _Using the REST API for updating Microsoft Edge Add-ons_.
+
 
 <!-- ------------------------------ -->
 #### Request
@@ -34,6 +37,15 @@ Uploads a package to update an existing draft submission of an add-on product.
 |---|---|
 | `POST` | `/products/{productID}/submissions/draft/package` |
 
+<!-- todo: 
+change {operationID} to  $operationID  ?
+change {productID}   to  $productID    ?
+change {operationID} to  $operationID  ?
+
+like format used in using.md 
+global, consistency pass in using.md & ref.md
+-->
+
 
 <!-- ---------- -->
 ###### URI parameters
@@ -42,6 +54,10 @@ Uploads a package to update an existing draft submission of an add-on product.
 |---|---|
 | `productID` | Required.  The product ID of the product to which the package must be uploaded. |
 
+<!-- todo: in these tables, change eg productID to $productID ? 
+global, consistency pass in using.md & ref.md
+-->
+
 
 <!-- ---------- -->
 ###### Request headers
@@ -50,23 +66,13 @@ The following request headers are required:
 
 ##### [v1.1](#tab/v1-1)
 
-* `Authorization: ApiKey <api key>`
-* `X-ClientID: <client ID>`
+* `Authorization: ApiKey $ApiKey`
+* `X-ClientID: $ClientID`
 * `Content-Type: application/zip`
 
-<!-- todo: 
-change <client ID> to $ClientID ?
-change <api key> to $ApiKey ?
-change order?
-per using.md:
-Authorization: ApiKey $ApiKey; Content-Type: application/zip; X-ClientID $ClientID
-
-global in article, & check using.md
--->
-
 ##### [v1](#tab/v1)
 
-* `Authorization: Bearer <auth token>`
+* `Authorization: Bearer $TOKEN`
 * `Content-Type: application/zip`
 
 ---
@@ -87,6 +93,8 @@ global in article, & check using.md
 
 * Location: `{operationID}`
 
+The response includes an operation ID, to send to other endpoints.
+
 
 <!-- ---------- -->
 ###### Status codes
@@ -106,9 +114,12 @@ See also:
 
 <!-- ====================================================================== -->
 ## Check the status of a package upload
+<!-- endpoint 2: GET submissions/draft/package/operations/$operationID -->
 
 Gets the status of the package upload.
 
+See also [Checking the status of a package upload](./using-addons-api.md#checking-the-status-of-a-package-upload) in _Using the REST API for updating Microsoft Edge Add-ons_.
+
 
 <!-- ------------------------------ -->
 #### Request
@@ -133,12 +144,12 @@ The following request headers are required:
 
 ##### [v1.1](#tab/v1-1)
 
-* `Authorization: ApiKey <api key>`
-* `X-ClientID: <client ID>`
+* `Authorization: ApiKey $ApiKey`
+* `X-ClientID: $ClientID`
 
 ##### [v1](#tab/v1)
 
-* `Authorization: Bearer <auth token>`
+* `Authorization: Bearer $TOKEN`
 
 ---
 
@@ -227,9 +238,12 @@ See also:
 
 <!-- ====================================================================== -->
 ## Publish the product draft submission
+<!-- endpoint 3: POST /submissions -->
 
 Publishes the current draft of the product to Microsoft Edge Add-ons.
 
+See also [Publishing the submission](./using-addons-api.md#publishing-the-submission) in _Using the REST API for updating Microsoft Edge Add-ons_.
+
 
 <!-- ------------------------------ -->
 #### Request
@@ -254,12 +268,12 @@ The following request headers are required:
 
 ##### [v1.1](#tab/v1-1)
 
-* `Authorization: ApiKey <api key>`
-* `X-ClientID: <client ID>`
+* `Authorization: ApiKey $ApiKey`
+* `X-ClientID: $ClientID`
 
 ##### [v1](#tab/v1)
 
-* `Authorization: Bearer <auth token>`
+* `Authorization: Bearer $TOKEN`
 
 ---
 
@@ -279,6 +293,8 @@ The following request headers are required:
 
 * Location: `{operationID}`
 
+The response includes an operation ID, to send to other endpoints.
+
 
 <!-- ---------- -->
 ###### Status codes
@@ -298,9 +314,12 @@ See also:
 
 <!-- ====================================================================== -->
 ## Check the publishing status
+<!-- endpoint 4: GET /submissions/operations/$operationID -->
 
 Checks the status of the publish operation.
 
+See also [Checking the publishing status](using-addons-api.md#checking-the-publishing-status) in _Using the REST API for updating Microsoft Edge Add-ons_.
+
 
 <!-- ------------------------------ -->
 #### Request
@@ -324,12 +343,12 @@ The following request headers are required:
 
 ##### [v1.1](#tab/v1-1)
 
-* `Authorization: ApiKey <api key>`
-* `X-ClientID: <client ID>`
+* `Authorization: ApiKey $ApiKey`
+* `X-ClientID: $ClientID`
 
 ##### [v1](#tab/v1)
 
-* `Authorization: Bearer <auth token>`
+* `Authorization: Bearer $TOKEN`
 
 ---
 
@@ -345,6 +364,8 @@ None.
 
 A `GET` operation status API can be called in the following scenarios.  In all valid scenarios, `200 OK` is returned, with different status messages.
 
+The response includes an operation ID, to send to other endpoints.
+
 
 <!-- ---------- -->
 ###### Response when a new product is published
@@ -543,4 +564,4 @@ Here's a list of common error codes and possible reasons.  For a full list, see
 <!-- all article-level links in article body: -->
 * [Using the REST API for updating Microsoft Edge Add-ons](./using-addons-api.md)
 * [Partner Center REST error codes](/partner-center/develop/error-codes) in Partner Center docs.
-* [List of HTTP status codes](https://wikipedia.org/wiki/List_of_HTTP_status_codes) at Wikipedia.
+* [List of HTTP status codes](https://wikipedia.org/wiki/List_of_HTTP_status_codes) at Wikipedia.

microsoft-edge/extensions-chromium/publish/api/using-addons-api.md

@@ -174,8 +174,9 @@ Header Parameters: Content-Type: application/x-www-form-urlencoded
 
 <!-- ---------- -->
 ###### Sample request
+<!-- to retrieve access token (v1 only) -->
 
-For example, to get an access token, send a POST request to the access token URL, as follows:
+For example, to get an access token, send a POST request to the access token URL, by entering a `curl` command at the command prompt, as follows:
 
 ```console
 > curl \
@@ -242,26 +243,29 @@ To create a new product or update a product's metadata, you must use Microsoft P
 
 <!-- ====================================================================== -->
 ## Uploading a package to update an existing submission
-<!-- endpoint 1 -->
+<!-- endpoint 1: POST /submissions/draft/package -->
 
 Use this REST API endpoint to update the package for an add-on.  This API uploads a package to update an existing draft submission of an add-on product.
 
+See also [Upload a package to update an existing submission](./addons-api-reference.md#upload-a-package-to-update-an-existing-submission) in _REST API Reference for updating Microsoft Edge Add-ons_.
+
 
 <!-- ---------------------------------------------- -->
 #### Endpoint description
-<!-- todo: must label these code blocks that are above the "Sample" section headings code blocks - Global in both article
-what kind of code block is each of these?  3 different kinds in 2 different articles = 3 different kinds of code blocks?
--->
 
 ##### [v1.1](#tab/v1-1)
 
 ```REST
 Endpoint: /v1/products/$productID/submissions/draft/package
 Type: POST
-Header Parameters: Authorization: ApiKey $ApiKey; Content-Type: application/zip; X-ClientID: $ClientID
+Header Parameters: Authorization: ApiKey $ApiKey; X-ClientID: $ClientID; Content-Type: application/zip
 Body content: the package file to upload
 ```
 
+<!-- todo: change /v1/ to /v1-1/ ?
+global in using.md & ref.md 
+-->
+
 ##### [v1](#tab/v1)
 
 ```REST
@@ -290,6 +294,9 @@ To get the product ID:
 
 <!-- ---------------------------------- -->
 #### Sample request
+<!-- for endpoint 1 -->
+
+To upload a package to update an existing submission, use the `curl` command at a command prompt as follows:
 
 ##### [v1.1](#tab/v1-1)
 
@@ -327,10 +334,14 @@ See also:
 
 <!-- ====================================================================== -->
 ## Checking the status of a package upload
-<!-- endpoint 2 -->
+<!-- endpoint 2: GET submissions/draft/package/operations/$operationID -->
 
 Use this API to check the status of package upload.
 
+`$operationID` is the operation ID that's returned in the response header from [Uploading a package to update an existing submission](#uploading-a-package-to-update-an-existing-submission) or [Publishing the submission](#publishing-the-submission).
+
+See also [Check the publishing status](./addons-api-reference.md#check-the-publishing-status) in _REST API Reference for updating Microsoft Edge Add-ons_.
+
 
 <!-- ---------------------------------------------- -->
 #### Endpoint description
@@ -356,6 +367,9 @@ Header Parameters: Authorization: Bearer $TOKEN
 
 <!-- ---------------------------------- -->
 #### Sample request
+<!-- for endpoint 2 -->
+
+To check the status of a package upload, use the `curl` command at the command prompt as follows:
 
 ##### [v1.1](#tab/v1-1)
 
@@ -386,10 +400,12 @@ See also:
 
 <!-- ====================================================================== -->
 ## Publishing the submission
-<!-- endpoint 3 -->
+<!-- endpoint 3: POST /submissions -->
 
 Use this API to publish the current draft of the product to the Microsoft Edge Add-ons website.
 
+See also [Publish the product draft submission](./addons-api-reference.md#publish-the-product-draft-submission) in _REST API Reference for updating Microsoft Edge Add-ons_.
+
 
 <!-- ---------------------------------------------- -->
 #### Endpoint description
@@ -417,6 +433,9 @@ Body content: Notes for certification, in JSON format
 
 <!-- ---------------------------------- -->
 #### Sample request
+<!-- for endpoint 3 -->
+
+To publish the submission, use the `curl` command at the command prompt as follows:
 
 ##### [v1.1](#tab/v1-1)
 
@@ -451,10 +470,14 @@ See also:
 
 <!-- ====================================================================== -->
 ## Checking the publishing status
-<!-- endpoint 4 -->
+<!-- endpoint 4: GET /submissions/operations/$operationID -->
 
 Use this API to check the status of the publish operation.
 
+`$operationID` is the operation ID that's returned in the response header from [Uploading a package to update an existing submission](#uploading-a-package-to-update-an-existing-submission) or [Publishing the submission](#publishing-the-submission).
+
+See also [Check the publishing status](./addons-api-reference.md#check-the-publishing-status) in _REST API Reference for updating Microsoft Edge Add-ons_.
+
 
 <!-- ---------------------------------------------- -->
 #### Endpoint description
@@ -480,6 +503,9 @@ Header Parameters: Authorization: Bearer $TOKEN
 
 <!-- ---------------------------------- -->
 #### Sample request
+<!-- for endpoint 4 -->
+
+To check the publishing status, use the `curl` command at the command prompt as follows:
 
 ##### [v1.1](#tab/v1-1)