Clarifications and formatting

api.md

@@ -7,27 +7,50 @@ Adspect provides a REST API for automating various tasks:
 * [Managing guest access to reporting](api.md#guest-access-to-reporting)
 * [Retrieving reports](api.md#reporting-api)
 
-Adspect API supports JSON and XML data encoding.  Examples below use JSON encoding for simplicity.
+The base URL for all API endpoints is `https://api.adspect.net/v1/`.  Endpoint descriptions below specify paths relative to this
+base URL.  HTTP method (verb) comes first, followed by the relative endpoint path, for example:
+
+```
+GET /streams
+```
+
+This endpoint description means making a GET request to `https://api.adspect.net/v1/streams`.
+
+The API supports JSON and XML data encoding.  Examples below use JSON encoding for simplicity.
 
 ## Authentication
 
-Adspect REST API employs
+Adspect API employs
 [HTTP Basic authentication scheme](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#Basic_authentication_scheme)
 in which API key is supplied as username and password is left blank.  You may find your API key in profile.
 
 Each API request must contain two mandatory headers:
 
-1. `Authorization: Basic <authKey>` to authenticate yourself with Adspect;
-2. `Content-Type` for selecting content data encoding:
-   * `Content-Type: application/json` for JSON data encoding;
-   * `Content-Type: application/xml` for XML data encoding.
+:::{list-table}
+:header-rows: 1
 
-The `<authKey>` field in the Authorization header is formed by [base64-encoding](https://en.wikipedia.org/wiki/Base64)
-a string composed of the API key and a colon appended to it.
+* - Header
+  - Value
+  - Description
+
+* - `Authorization`
+  - `Basic AUTHKEY`
+  - Authenticate for an Adspect account with its API key (see below.)
+
+* - `Content-Type`
+  - `application/json` or `application/xml`
+  - Select JSON or XML data encoding, respectively.
+:::
+
+The `AUTHKEY` placeholder in the Authorization header must be replaced by a [base64-encoded](https://en.wikipedia.org/wiki/Base64)
+string composed of the API key and a colon appended to it.
 
 Example code in PHP:
 
-```php
+```{code-block} php
+:emphasize-lines: 3
+:lineno-start: 1
+
 <?php
 $apiKey = 'SEbMw152aoe2ArffS7yjEJzJ_MFnd33e';
 $authKey = base64_encode($apiKey . ':');
@@ -48,12 +71,6 @@ $curl = curl_init();
 curl_setopt($curl, CURLOPT_USERPWD, $apiKey . ':');
 ```
 
-## Endpoints
-
-The base URL for all API endpoints is `https://api.adspect.net/v1/`.  Endpoint descriptions below specify
-paths relative to this base URL.  HTTP method (verb) comes first, followed by the relative endpoint path,
-e.g. the description `GET /streams` means making a GET request to the `https://api.adspect.net/v1/streams` URL.
-
 ## Collections
 
 Certain object properties may take values only from concrete finite sets--collections.  The table below lists collection endpoints: