diff --git a/components/ErrorResponse.yml b/components/ErrorResponse.yml
new file mode 100644
index 00000000..087dcbe7
--- /dev/null
+++ b/components/ErrorResponse.yml
@@ -0,0 +1,33 @@
+openapi: 3.0.0
+info:
+ version: "0.0.3-unstable"
+ title: VC HTTP API
+ description: This is an Experimental Open API Specification for the [VC Data Model](https://www.w3.org/TR/vc-data-model/).
+ license:
+ name: W3C Software and Document License
+ url: http://www.w3.org/Consortium/Legal/copyright-software.
+ contact:
+ name: GitHub Source Code
+ url: https://github.com/w3c-ccg/vc-api
+paths:
+components:
+ schemas:
+ ErrorResponse:
+ type: object
+ description: A response that denotes that an error has occurred.
+ properties:
+ id:
+ type: "string"
+ pattern: "[a-z0-9\\-]{8,}"
+ message:
+ type: "string"
+ minLength: 10
+ maxLength: 100
+ details:
+ type: "object"
+ required: ["id", "message"]
+ example:
+ {
+ "id": "invalid-json",
+ "message": "The provided JSON data was malformed."
+ }
diff --git a/components/parameters/path/ExchangeId.yml b/components/parameters/path/ExchangeId.yml
new file mode 100644
index 00000000..5f58676e
--- /dev/null
+++ b/components/parameters/path/ExchangeId.yml
@@ -0,0 +1,8 @@
+name: exchange-id
+description: A potentially human-readable identifier for an exchange.
+in: path
+required: true
+schema:
+ type: string
+ minimum: 3
+ pattern: "[a-z0-9][a-z0-9\\-]{2,}"
diff --git a/components/parameters/path/TransactionUuid.yml b/components/parameters/path/TransactionUuid.yml
new file mode 100644
index 00000000..1aa2c3df
--- /dev/null
+++ b/components/parameters/path/TransactionUuid.yml
@@ -0,0 +1,6 @@
+in: path
+name: transaction-uuid
+required: true
+schema:
+ type: string
+ pattern: "([0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12}){0,1}"
diff --git a/holder.yml b/holder.yml
index 98c57eb7..fc011a7e 100644
--- a/holder.yml
+++ b/holder.yml
@@ -56,60 +56,85 @@ paths:
description: invalid input!
"500":
description: error!
- /presentations/available:
+ /exchanges/{exchange-id}:
post:
- summary: Notifies a holder of an available presentation.
- operationId: notifyPresentationAvailable
+ summary: Initiates an exchange of information.
+ operationId: initiateExchange
description:
- This API is the first part of a holder to holder credential exchange over http.
- Notifies this server-holder that the client-holder (caller) is prepared to deliver a presentation compliant with the provided Verifiable Presentation Request query. This is the first part of a presentation exchange over this HTTP API. This server-holder MUST return the required 'domain' and 'challenge' parameters for the Presentation. This server-holder MAY reply with an alternate Verifiable Presentation Request query if it requires something different than the one proposed by the client-holder. The client-holder MUST return a Presentation in accordance with the response parameters.
+ A client can use this endpoint to initiate an exchange of a particular
+ type. The client can include HTTP POST information related to the
+ details of exchange it would like to initiate. If the server understands
+ the request, it returns a Verifiable Presentation Request. A request
+ that the server cannot understand results in an error.
+ parameters:
+ - $ref: "./components/parameters/path/ExchangeId.yml"
requestBody:
- description: Details the client provides to the server to help it decide if the presentation should be made.
+ description:
+ Information related to the type of exchange the client would like
+ to start.
content:
application/json:
schema:
- $ref: "#/components/schemas/NotifyPresentationAvailableRequest"
+ anyOf:
+ -
+ {
+ "type": "object",
+ "description": "Data necessary to initiate the exchange."
+ }
+ -
+ $ref: "#/components/schemas/NotifyPresentationAvailableRequest"
responses:
"200":
- description: Proceed with presentation
+ description: Proceed with exchange.
content:
application/json:
schema:
- $ref: "#/components/schemas/NotifyPresentationAvailableResponse"
+ $ref: "#/components/schemas/VerifiablePresentationRequest"
"400":
- description: Request for presentation is malformed
+ description: Request is malformed.
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorResponse"
"501":
- description: Not implemented
+ description: Service not implemented.
"500":
- description: internal error
- /presentations/submissions:
- post:
- summary: Provide a presentation for a holder to store.
- operationId: storePresentation
- description: "Delivery endpoint for a client-holder to provide a presentation in compliance with the Verifiable Presentation Request provided in the Notification call. This server-holder MUST match the 'domain' and 'challenge' to a 'domain' and 'challenge' previously sent in a Notification Response, and not already received. The server-holder MUST verify the Presentation. The server MUST store the Presentation if verification passes."
+ description: Internal server error.
+ /exchanges/{exchange-id}/{transaction-uuid}:
+ put:
+ summary: Receives information related to an existing exchange.
+ operationId: receiveExchangeData
+ description:
+ A client can use this endpoint to continue the exchange of information
+ associated with an initiated exchange by sending a Verifiable Presentation
+ with information requested by the server to this endpoint.
+ parameters:
+ - $ref: "./components/parameters/path/ExchangeId.yml"
+ - $ref: "./components/parameters/path/TransactionUuid.yml"
requestBody:
- description: Details the client provides to the server to help it decide if the presentation should be made.
+ description:
+ A Verifiable Presentation.
content:
application/json:
schema:
- $ref: "#/components/schemas/StorePresentationRequest"
+ $ref: "#/components/schemas/VerifiablePresentation"
responses:
- "202":
- description: Presentation accepted
+ "200":
+ description: Received data was accepted.
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/VerifiablePresentationRequest"
"400":
- description: Presentation is malformed
- "401":
- description: Presentation did not contain a proof
- "402":
- description: Payment required
- "403":
- description: Presentation verification failed
- "425":
- description: Server is unwilling to risk processing a request that might be replayed
- "501":
- description: Not implemented
+ description: Received data is malformed.
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorResponse"
"500":
- description: internal error
+ description: Internal server error.
+ "501":
+ description: Service not implemented.
components:
schemas:
DeriveCredentialRequest:
@@ -213,5 +238,11 @@ components:
"domain": "jobs.example.com",
"challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f",
}
+ ErrorResponse:
+ $ref: "./components/ErrorResponse.yml#/components/schemas/ErrorResponse"
StorePresentationRequest:
$ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation"
+ VerifiablePresentation:
+ $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation"
+ VerifiablePresentationRequest:
+ $ref: "./components/VerifiablePresentationRequest.yml#/components/schemas/VerifiablePresentationRequest"
diff --git a/index.html b/index.html
index 0f452eb3..3c1e7779 100644
--- a/index.html
+++ b/index.html
@@ -555,21 +555,21 @@ Prove Presentation
- Presentation Availability
+ Initiate Exchange
+ data-api-endpoint="post /exchanges/{exchange-id}">
- Submit Presentation
+ Continue Exchange
+ data-api-endpoint="put /exchanges/{exchange-id}/{transaction-uuid}">