Adding section that details API Endpoints by Component (#384)

Updated all "path" OAS objects found in all yml files to include a new parameter called x-expectedCaller to index which component is expected to call the given endpoint. 

Updated respec-oas.js to have a new table generation function to generate expectedCaller tables.

Updated index.html to include a new section before the API details that indexes all endpoints and their expectedCallers. 
---------

Co-authored-by: Eric Schuh <eric@legreq.com>

exchanges.yml

@@ -24,6 +24,7 @@ paths:
         - zCap: []
       operationId: createWorkflow
       description: Creates a new workflow and returns workflowId in the response body.
+      x-expectedCaller: Administrators
       requestBody:
         content:
           application/json:
@@ -53,6 +54,7 @@ paths:
         - zCap: []
       operationId: getWorkflowConfiguration
       description: Gets the configuration of an existing workflow and returns it in the response body.
+      x-expectedCaller: Administrators
       parameters:
         - $ref: "./components/parameters/path/LocalWorkflowId.yml"
       responses:
@@ -79,6 +81,7 @@ paths:
         - zCap: []
       operationId: createExchange
       description: Creates a new exchange and returns exchangeId and time to live in the response body.
+      x-expectedCaller: Owner Coordinator
       parameters:
         - $ref: "./components/parameters/path/LocalWorkflowId.yml"
       requestBody:
@@ -110,6 +113,7 @@ paths:
         - zCap: []
       operationId: getExchangeConfiguration
       description: Gets the configuration of an existing exchange and returns it in the response body.
+      x-expectedCaller: Owner Coordinator
       parameters:
         - $ref: "./components/parameters/path/LocalWorkflowId.yml"
         - $ref: "./components/parameters/path/LocalExchangeId.yml"
@@ -136,6 +140,7 @@ paths:
         - zCap: []
       operationId: participateInExchange
       description: Participate in an exchange. Posting an empty body will start the exchange or return what the exchange is expecting to complete the next step.
+      x-expectedCaller: Anyone
       parameters:
         - $ref: "./components/parameters/path/LocalWorkflowId.yml"
         - $ref: "./components/parameters/path/LocalExchangeId.yml"

holder.yml

@@ -22,6 +22,7 @@ paths:
        - oAuth2: []
        - zCap: []
       summary: Gets a credential or verifiable credential by ID. To get a credential that does not have credential.id set but has an associated credentialId value, pass credentialId instead.
+      x-expectedCaller: "Issuer Coordinator"
       operationId: getCredential
       parameters:
         - $ref: "./components/parameters/path/ObjectId.yml"
@@ -56,6 +57,7 @@ paths:
        - oAuth2: []
        - zCap: []
       summary: Deletes a credential or verifiable credential by ID. To delete a credential that does not have credential.id set but has an associated credentialId value, pass credentialId instead.
+      x-expectedCaller: "Issuer Coordinator"
       operationId: deleteCredential
       parameters:
         - $ref: "./components/parameters/path/ObjectId.yml"
@@ -84,6 +86,7 @@ paths:
        - zCap: []
       summary: Gets list of credentials or verifiable credentials
       operationId: getCredentials
+      x-expectedCaller: "Holder Coordinator or Issuer Coordinator"
       parameters:
         - in: query
           name: type
@@ -125,6 +128,7 @@ paths:
       summary: Derives a credential and returns it in the response body.
       operationId: deriveCredential
       description: Derives a credential and returns it in the response body.
+      x-expectedCaller: "Holder Coordinator"
       requestBody:
         content:
           application/json:
@@ -155,6 +159,7 @@ paths:
        - oAuth2: []
        - zCap: []
       operationId: getPresentation
+      x-expectedCaller: "Holder Coordinator"
       parameters:
         - $ref: "./components/parameters/path/ObjectId.yml"
       responses:
@@ -187,6 +192,7 @@ paths:
        - oAuth2: []
        - zCap: []
       operationId: deletePresentation
+      x-expectedCaller: "Holder Coordinator"
       parameters:
         - $ref: "./components/parameters/path/ObjectId.yml"
       responses:
@@ -214,6 +220,7 @@ paths:
        - oAuth2: []
        - zCap: []
       operationId: getPresentations
+      x-expectedCaller: "Holder Coordinator"
       parameters:
         - in: query
           name: type
@@ -253,6 +260,7 @@ paths:
        - oAuth2: []
        - zCap: []
       operationId: createPresentation
+      x-expectedCaller: "Holder Coordinator"
       description: Creates a presentation and returns it in the response body.
       requestBody:
         content:

index.html

@@ -686,6 +686,62 @@ <h3>Content Serialization</h3>
       </p>
     </section>
 
+    <section>
+      <h3>API Component Overview</h3>
+        <p>
+          This section gives an overview of all endpoints in the VC-API by the component the endpoint is expected be callable from. 
+          If a component does not have a listing below it means the VC-API does not currently specify any endpoints for that component. 
+        </p>
+
+      <h4>Issuer Coordinator</h4>
+      <p>
+        Below are all endpoints expected to be exposed by the Issuer Coordinator, along with the component
+        that is expected to call the endpoint
+      </p>
+      <table class="simple api-component-table"
+        data-api-path="/credentials"></table>
+
+      <h4>Issuer Service</h4>
+      <p>
+        Below are all endpoints expected to be exposed by the Issuer Service, along with the component
+        that is expected to call the endpoint
+      </p>
+      <table class="simple api-component-table"
+        data-api-path="/credentials/issue /credentials /credentials/{id}"></table>
+
+      <h4>Status Service</h4>
+      <p>
+        Below are all endpoints expected to be exposed by the Status Service, along with the component
+        that is expected to call the endpoint
+      </p>
+      <table class="simple api-component-table"
+        data-api-path="/credentials/status"></table>
+
+      <h4>Verification Service</h4>
+      <p>
+        Below are all endpoints expected to be exposed by the Verification Service, along with the component
+        that is expected to call the endpoint
+      </p>
+      <table class="simple api-component-table"
+        data-api-path="/credentials/verify /presentations/verify /challenges"></table>
+
+      <h4>Holder Service</h4>
+      <p>
+        Below are all endpoints expected to be exposed by the Holder Service, along with the component
+        that is expected to call the endpoint
+      </p>
+      <table class="simple api-component-table"
+        data-api-path="/credentials/derive /presentations/prove /presentations /presentations/{id}"></table>
+
+      <h4>Workflow Service</h4>
+      <p>
+        Below are all endpoints expected to be exposed by the Workflow Service, along with the component
+        that is expected to call the endpoint
+      </p>
+      <table class="simple api-component-table"
+        data-api-path="/workflows /workflows/{localWorkflowId} /workflows/{localWorkflowId}/exchanges /workflows/{localWorkflowId}/exchanges/{localExchangeId}"></table>
+
+    </section>
     <section>
       <h3>Issuing</h3>
       <p>

issuer.yml

@@ -23,6 +23,7 @@ paths:
         - oAuth2: []
         - zCap: []
       operationId: issueCredential
+      x-expectedCaller: "Issuer Coordinator"
       description: Issues a credential and returns it in the response body.
       requestBody:
         content:
@@ -54,6 +55,7 @@ paths:
         - oAuth2: []
         - zCap: []
       operationId: updateCredentialStatus
+      x-expectedCaller: "Verifier Service"
       description: Updates the status of an issued credential.
       requestBody:
         content:

respec-oas.js

@@ -14,6 +14,36 @@ function getEndpoint({apis, path}) {
   return endpoint;
 }
 
+function buildComponentTables({config, document, apis}) {
+  const apiTables = document.querySelectorAll("table.api-component-table");
+
+  // process every table
+  for(const table of apiTables) {
+    // set up the API component table headers
+    const tableHeader = document.createElement('tr');
+    tableHeader.innerHTML = '<th>Endpoint</th><th>Expected Caller</th>';
+    table.appendChild(tableHeader);
+
+    // summarize each API endpoint
+    for(const path of table.dataset.apiPath.split(/\s+/)) {
+      if(path.trim().length > 0) {
+        const endpoint = getEndpoint({apis, path});
+        for(const verb in endpoint) {
+          var expectedCaller = endpoint[verb]['x-expectedCaller'];
+          const tableRow = document.createElement('tr');
+          if(expectedCaller === undefined)
+          {
+            expectedCaller = "Expected Caller Undefined";;
+          }
+          tableRow.innerHTML =
+            `<td>${verb.toUpperCase()}&nbsp;${path}</td><td>${expectedCaller}</td>`;
+          table.appendChild(tableRow);
+        }
+      }
+    }
+  }
+}
+
 function buildApiSummaryTables({config, document, apis}) {
   const apiTables = document.querySelectorAll("table.api-summary-table");
 
@@ -342,6 +372,7 @@ async function injectOas(config, document) {
 
     buildApiSummaryTables({config, document, apis});
     buildEndpointDetails({config, document, apis});
+    buildComponentTables({config, document, apis});
   } catch(err) {
     console.error(err);
   }

verifier.yml

@@ -23,6 +23,7 @@ paths:
        - oAuth2: []
        - zCap: []
       operationId: verifyCredential
+      x-expectedCaller: "Verification Coordinator"
       description: Verifies a verifiableCredential and returns a verificationResult in the response body.
       requestBody:
         content:
@@ -51,6 +52,7 @@ paths:
        - oAuth2: []
        - zCap: []
       operationId: verifyPresentation
+      x-expectedCaller: "Verification Coordinator"
       description: Verifies a verifiablePresentation and returns a verificationResult in the response body.  Given the possibility of denial of service, buffer overflow, or other style attacks, an implementation is permitted to rate limit or restrict requests against this API endpoint to those requests that contain only a single credential with a 413 or 429 error code as appropriate.
       requestBody:
         content:
@@ -83,6 +85,7 @@ paths:
        - oAuth2: []
        - zCap: []
       operationId: challenge
+      x-expectedCaller: "Verification Coordinator"
       description: Creates a challenge to be used as `options.challenge` in future requests.
       responses:
         "200":

versions/v0.0.2/vc-api.yml

@@ -23,6 +23,7 @@ paths:
         - Issuer
       summary: Issues a credential and returns it in the response body.
       operationId: issueCredential
+      x-expectedCaller: "Issuer Coordinator"
       description: Issues a credential and returns it in the response body.
       requestBody:
         content:
@@ -47,6 +48,7 @@ paths:
         - Holder
       summary: Derives a credential and returns it in the response body.
       operationId: deriveCredential
+      x-expectedCaller: "Holder Coordinator"
       description: Derives a credential and returns it in the response body.
       requestBody:
         content:
@@ -73,6 +75,7 @@ paths:
         - Issuer
       summary: Updates the status of an issued credential
       operationId: updateCredentialStatus
+      x-expectedCaller: "Status Service"
       description: Updates the status of an issued credential.
       requestBody:
         content:
@@ -95,6 +98,7 @@ paths:
         - Holder
       summary: Proves a presentation and returns it in the response body.
       operationId: provePresentation
+      x-expectedCaller: "Holder Coordinator"
       description: Proves a presentation and returns it in the response body.
       requestBody:
         content:
@@ -119,6 +123,7 @@ paths:
         - Verifier
       summary: Verifies a verifiableCredential and returns a verificationResult in the response body.
       operationId: verifyCredential
+      x-expectedCaller: "Verification Coordinator"
       description: Verifies a verifiableCredential and returns a verificationResult in the response body.
       requestBody:
         content:
@@ -143,6 +148,7 @@ paths:
         - Verifier
       summary: Verifies a Presentation with or without proofs attached and returns a verificationResult in the response body.
       operationId: verifyPresentation
+      x-expectedCaller: "Verification Coordinator"
       description: Verifies a verifiablePresentation and returns a verificationResult in the response body.  Given the possibility of denial of service, buffer overflow, or other style attacks, an implementation is permitted to rate limit or restrict requests against this API endpoint to those requests that contain only a single credential with a 413 or 429 error code as appropriate.
       requestBody:
         content: