Update Aviary API docs to reference Swagger (#229)

This patch makes use of the new shared Swagger instance to avoid
manually documenting artifact repository endpoints.

It also adds a new authentication section which can be referenced by
Swagger in the future, to help with generating a valid basic auth token.

The webhook checksum section was expanded slightly to make it clear that
the purpose of the checksum is validating the request, rather than just
documenting that the checksum is provided.

Author: cd-work

docs/artifact_repositories/api.md

@@ -1,85 +1,39 @@
 # API
 
-This section documents the public API for Phylum's artifact repository offering.
+This section provides additional instructions for usage of Phylum's Artifact
+Repository API. The full API is documented on [Swagger].
 
-## Webhooks
+[Swagger]: https://swagger.phylum.io/?urls.primaryName=Artifact+Repository+API
 
-Webhooks will send out notifications whenever a package that was accessed
-through a repository proxy fails analysis.
+## Authentication
 
-To setup a new webhook, you can use the following curl command:
+The Artifact Repository API expects authentication in the basic auth format. The
+username is optional and provides context for which group should be used for the
+request. The group must either be the group name itself, for standalone groups,
+or the organization and group name combined using a `/`.
 
-```sh
-# Phylum group used with the registry proxy.
-export PHYLUM_GROUP=…
-# https://docs.phylum.io/knowledge_base/api-keys#generate-an-api-key
-export PHYLUM_API_KEY=…
-# URL which will be called on analysis failure.
-export WEBHOOK_URL=…
-# Shared secret used to validate authenticity of webhook callbacks
-export SECRET=…
+The following script will create a valid authorization token for the org
+`phylum`, group `demo`, and with the token stored in `$PHYLUM_API_KEY`:
 
-curl \
-    -X PUT \
-    --user "$PHYLUM_GROUP:$PHYLUM_API_KEY" \
-    --json "{\"url\": \"$WEBHOOK_URL\", \"secret\": \"$SECRET\"}" \
-    "https://aviary.phylum.io/webhooks"
+```sh
+echo "Basic $(printf \"phylum/demo:$PHYLUM_API_KEY\" | base64)"
 ```
 
-> ⚠️ **WARNING** ⚠️
->
-> Do not accidentally save your token into your shell history.
+## Webhooks
+
+Webhooks will send out notifications whenever a package that was accessed
+through a repository proxy fails analysis.
 
-Once a webhook is registered, policy violations will be sent to it in the same
-format as the [package check endpoint].
+Once a webhook is [registered][register webhook endpoint], policy violations
+will be sent to it in the same format as the [package check endpoint].
 
 Since these reports contain security advisories, it's important to make sure
 that they were generated by Phylum and the endpoint wasn't called by a third
 party. To make this possible, all official webhook notification calls will
 include a `sha256` query parameter which contains a hexadecimal representation
 of the SHA256-HMAC of the response body, generated with the shared secret
-provided when registering the webhook.
-
-### Deleting Webhooks
-
-If a webhook is no longer in use, it should be deleted:
-
-```sh
-# Phylum group used with the registry proxy.
-export PHYLUM_GROUP=…
-# https://docs.phylum.io/knowledge_base/api-keys#generate-an-api-key
-export PHYLUM_API_KEY=…
-# URL-encoded URL used during webhook setup.
-export WEBHOOK_URL=…
-
-curl \
-    -X DELETE \
-    --user "$PHYLUM_GROUP:$PHYLUM_API_KEY" \
-    "https://aviary.phylum.io/webhooks/$WEBHOOK_URL"
-```
-
-> ⚠️ **WARNING** ⚠️
->
-> Do not accidentally save your token into your shell history.
-
-### Retrieving configured Webhooks
-
-To get a list with all configured webhook URLs for a group, you can send a `GET`
-request to the `/webhooks` endpoint:
-
-```sh
-# Phylum group used with the registry proxy.
-export PHYLUM_GROUP=…
-# https://docs.phylum.io/knowledge_base/api-keys#generate-an-api-key
-export PHYLUM_API_KEY=…
-
-curl \
-    --user "$PHYLUM_GROUP:$PHYLUM_API_KEY" \
-    "https://aviary.phylum.io/webhooks"
-```
-
-> ⚠️ **WARNING** ⚠️
->
-> Do not accidentally save your token into your shell history.
+provided when registering the webhook. This checksum **must** be validated
+before accepting the authority of new webhook events.
 
-[package check endpoint]: https://api.phylum.io/api/v0/swagger/index.html#/Organizations/organizations_group_packages_check
+[register webhook endpoint]: https://swagger.phylum.io/?urls.primaryName=Artifact+Repository+API#/default/add_webhook
+[package check endpoint]: https://swagger.phylum.io/?urls.primaryName=API#/Organizations/organizations_group_packages_check