Improve language/examples around test suite API.

README.md

@@ -37,24 +37,29 @@ npm i
 
 ## Setup
 
-To integrate with this test suite, you will need a
-[VC-API compatible](https://w3c-ccg.github.io/vc-api/) issuer and verifier that
-are capable of issuing and verifying verifiable credentials and verifiable
-presentations. If your implementation is not VC-API compatible, it is possible
-to "wrap" the implementation in a minimal VC-API implementation, example code
-for which is available at <https://github.com/Wind4Greg/Server-for-VCs>.
-Additionally, your verifier will need to be able to verify Verifiable Credentials
+This test suite uses an HTTP API (based on the
+[VC-API](https://w3c-ccg.github.io/vc-api/)) for passing  credentials into
+issuer and verifier implementations. If your implementation is not already
+compatible with the VC-API, it is possible to "wrap" the implementation in a
+minimal VC-API implementation (example code is available at
+<https://github.com/Wind4Greg/Server-for-VCs>).
+
+Additionally, verifier implementations will need to be able to verify Verifiable Credentials
 and Verifiable Presentations signed with `eddsa-rdfc-2022`. We recommend
-that any issuer endpoints submitted to this test suite also issue using
+that any issuer endpoints used with this test suite also issue using
 `eddsa-rdfc-2022`. Both signed and unsigned Verifiable Presentations will
 be submitted for verification. Signed Verifiable Presentations from this suite
 will have a domain and challenge set. The domain should be the test repo, and
 the challenge is static.
 
-The issuer endpoint will need to conform to the
-[VC Issuer API](https://w3c-ccg.github.io/vc-api/#issue-credential).
+### Test Suite HTTP API
 
-A request to issue a credential (`/credentials/issue`) will look like this:
+
+A request to **issue a credential** (`/credentials/issue`) will look like this:
+
+```http
+POST /credentials/issue
+```
 
 ```json
 {
@@ -82,6 +87,10 @@ A request to issue a credential (`/credentials/issue`) will look like this:
 The response from a call to issue a credential (`/credentials/issue`) will
 look like this:
 
+```http
+HTTP/1.1 200 OK
+```
+
 ```json
 {
   "verifiableCredential": {
@@ -112,12 +121,13 @@ look like this:
 }
 ```
 
-The credential verifier endpoint will need to conform to the
-[VC Verifier API](https://w3c-ccg.github.io/vc-api/#verify-credential).
-
-A request to the verifier endpoint (`/credentials/verify`) for a credential
+A request to the **verifier endpoint** (`/credentials/verify`) for a credential
 will look like this:
 
+```http
+POST /credentials/verify
+```
+
 ```json
 {
   "verifiableCredential": {
@@ -147,13 +157,16 @@ will look like this:
   },
   "options": {}
 }
-
 ```
 
 A response from the verifier endpoint (`/credentials/verify`) for a
 verifiable credential might look like this (only HTTP response codes are
 checked):
 
+```http
+HTTP/1.1 200 OK
+```
+
 ```json
 {
   "checks": ["proof"],
@@ -162,11 +175,18 @@ checked):
 }
 ```
 
-The presentation verifier endpoint will need to conform to the
-[VC Verifier API](https://w3c-ccg.github.io/vc-api/#verify-presentation).
+The credential verifier endpoint is based on the
+[VC-API Verify Credential](https://w3c-ccg.github.io/vc-api/#verify-credential)
+endpoint.
 
-A request to the verifier endpoint for a presentation (`/presentations/verify`)
-will look like this:
+---
+
+A request to the **verifier endpoint** for a presentation
+(`/presentations/verify`) will look like this:
+
+```http
+POST /presentations/verify
+```
 
 ```json
 {
@@ -221,6 +241,10 @@ A response from the verifier endpoint (`/credentials/verify`) for a
 verifiable presentation might look like this (only HTTP response codes are
 checked):
 
+```http
+HTTP/1.1 200 OK
+```
+
 ```json
 {
   "checks": ["proof"],
@@ -229,6 +253,11 @@ checked):
 }
 ```
 
+The presentation verifier endpoint is based on the
+[VC API Verify Presentation](https://w3c-ccg.github.io/vc-api/#verify-presentation) endpoint.
+
+#### Required Contexts
+
 Implementations are expected to not error when any of the following context
 files are used in a verifiable credential or a verifiable presentation: