diff --git a/prism-agent/service/api/http/connect/schemas.yaml b/prism-agent/service/api/http/connect/schemas.yaml index 96afaf3945..63fb91d78f 100644 --- a/prism-agent/service/api/http/connect/schemas.yaml +++ b/prism-agent/service/api/http/connect/schemas.yaml @@ -5,7 +5,7 @@ components: in: path name: connectionId required: true - description: the unique identifier of the connection record + description: The unique identifier of the connection record. schema: type: string schemas: @@ -13,19 +13,23 @@ components: type: object properties: label: + description: A human readable alias for the connection. type: string example: "Peter" AcceptConnectionInvitationRequest: + description: The request used by an invitee to accept a connection invitation received from an inviter, using out-of-band mechanism. type: object required: - invitation properties: invitation: + description: The base64-encoded raw invitation. type: string example: "eyJAaWQiOiIzZmE4NWY2NC01NzE3LTQ1NjItYjNmYy0yYzk2M2Y2NmFmYTYiLCJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvbXktZmFtaWx5LzEuMC9teS1tZXNzYWdlLXR5cGUiLCJkaWQiOiJXZ1d4cXp0ck5vb0c5MlJYdnhTVFd2IiwiaW1hZ2VVcmwiOiJodHRwOi8vMTkyLjE2OC41Ni4xMDEvaW1nL2xvZ28uanBnIiwibGFiZWwiOiJCb2IiLCJyZWNpcGllbnRLZXlzIjpbIkgzQzJBVnZMTXY2Z21NTmFtM3VWQWpacGZrY0pDd0R3blpuNnozd1htcVBWIl0sInJvdXRpbmdLZXlzIjpbIkgzQzJBVnZMTXY2Z21NTmFtM3VWQWpacGZrY0pDd0R3blpuNnozd1htcVBWIl0sInNlcnZpY2VFbmRwb2ludCI6Imh0dHA6Ly8xOTIuMTY4LjU2LjEwMTo4MDIwIn0=" Connection: + description: A connection record. type: object allOf: - $ref: "#/components/schemas/CreateConnectionRequest" @@ -39,42 +43,48 @@ components: - invitation properties: self: + description: The reference to the connection resource. type: string example: https://atala-prism-products.io/connections/ABCD-1234 kind: + description: The type of object returned. In this case a `Connection`. type: string - example: ConnectionState + example: Connection connectionId: + description: The unique identifier of the connection. type: string format: uuid - example: "12345-9876" + example: "3fa85f64-5717-4562-b3fc-2c963f66afa6" myDid: + description: The DID representing me as the inviter or invitee in this specific connection. type: string - example: "did:prism:12345" + example: "did:peer:12345" theirDid: + description: The DID representing the other peer as the an inviter or invitee in this specific connection. type: string - example: "did:peer:12345" + example: "did:peer:67890" state: + description: The current state of the connection protocol execution. type: string enum: - [ - "InvitationGenerated", - "InvitationReceived", - "ConnectionRequestPending", - "ConnectionRequestSent", - "ConnectionRequestReceived", - "ConnectionResponsePending", - "ConnectionResponseSent", - "ConnectionResponseReceived", - "ProblemReportPending", - "ProblemReportSent", - "ProblemReportReceived", - ] + - InvitationGenerated + - InvitationReceived + - ConnectionRequestPending + - ConnectionRequestSent + - ConnectionRequestReceived + - ConnectionResponsePending + - ConnectionResponseSent + - ConnectionResponseReceived + - ProblemReportPending + - ProblemReportSent + - ProblemReportReceived createdAt: + description: The date and time the connection record was created. type: string format: date-time example: 2021-10-31T09:22:23Z updatedAt: + description: The date and time the connection record was last updated. type: string format: date-time example: 2021-12-31T13:59:60Z @@ -82,6 +92,7 @@ components: $ref: "#/components/schemas/ConnectionInvitation" ConnectionCollection: + description: A collection of connection records. type: object required: - self @@ -89,17 +100,21 @@ components: - contents properties: self: + description: The reference to the connection collection itself. type: string example: https://atala-prism-products.io/connections kind: + description: The type of object returned. In this case a `Collection`. type: string example: Collection contents: + description: The array containing the list of connection records. type: array items: $ref: "#/components/schemas/Connection" ConnectionInvitation: + description: A connection invitation. type: object required: - id diff --git a/prism-agent/service/api/http/pollux/parameters.yaml b/prism-agent/service/api/http/pollux/parameters.yaml index 4345b7dcd0..5629a32562 100644 --- a/prism-agent/service/api/http/pollux/parameters.yaml +++ b/prism-agent/service/api/http/pollux/parameters.yaml @@ -4,7 +4,7 @@ components: in: path name: recordId required: true - description: The issue credential record Id. + description: The unique identifier of the issue credential record. schema: type: string format: uuid diff --git a/prism-agent/service/api/http/pollux/schemas.yaml b/prism-agent/service/api/http/pollux/schemas.yaml index 4ff32fc8d8..eba911a9ec 100644 --- a/prism-agent/service/api/http/pollux/schemas.yaml +++ b/prism-agent/service/api/http/pollux/schemas.yaml @@ -236,21 +236,24 @@ components: properties: schemaId: type: string - description: Identifier of the VC Schema associated with this object + description: The unique identifier of the schema used for this credential offer. subjectId: type: string - description: Subject DID of the verifiable credentials object + description: The identifier (e.g DID) of the subject to which the verifiable credential will be issued. example: did:prism:subjectofverifiablecredentials validityPeriod: type: number - description: The validity period in seconds of the verifiable credential + description: The validity period in seconds of the verifiable credential that will be issued. example: 3600 claims: type: object - description: Claims that will be associated with given verifiable credentials + description: The claims that will be associated with the issued verifiable credential. additionalProperties: type: string automaticIssuance: + description: | + Specifies whether or not the credential should be automatically generated and issued when receiving the `CredentialRequest` from the holder. + If set to `false`, a manual approval by the issuer via API call will be required for the VC to be issued. type: boolean default: true awaitConfirmation: @@ -258,7 +261,7 @@ components: default: true CreateIssueCredentialRecordRequest: - description: A request to create a new "issue credential record" + description: A request to create a new "issue credential record". type: object allOf: - $ref: "#/components/schemas/IssueCredentialRecordBase" @@ -269,14 +272,14 @@ components: properties: issuingDID: type: string - description: Issuer DID of the verifiable credentials object + description: The issuer DID of the verifiable credential object. example: did:prism:issuerofverifiablecredentials connectionId: type: string - description: A connection ID between issuer and holder. + description: The unique identifier of a DIDComm connection that already exists between the issuer and the holder, and that will be used to execute the issue credential protocol. IssueCredentialRecord: - description: An issue credential record to store the state of the protocol execution + description: An issue credential record that stores the state of the protocol execution. type: object allOf: - $ref: "#/components/schemas/IssueCredentialRecordBase" @@ -288,20 +291,25 @@ components: - protocolState properties: recordId: + description: The unique identifier of the issue credential record. type: string format: uuid createdAt: + description: The date and time when the issue credential record was created. type: string format: date-time updatedAt: + description: The date and time when the issue credential record was last updated. type: string format: date-time role: + description: The role played by the Prism agent in the credential issuance flow. type: string enum: - Issuer - Holder protocolState: + description: The current state of the issue credential protocol execution. type: string enum: - OfferPending @@ -323,14 +331,15 @@ components: - PublicationQueued - Published jwtCredential: + description: The base64-encoded JWT verifiable credential that has been sent by the issuer. type: string issuingDID: type: string - description: Issuer DID of the verifiable credentials object + description: Issuer DID of the verifiable credential object. example: did:prism:issuerofverifiablecredentials IssueCredentialRecordCollection: - description: A collection of issue credential records + description: A collection of issue credential records. required: - items - offset @@ -338,6 +347,7 @@ components: - count properties: items: + description: The array containing the list of issue credential records. type: array items: $ref: "#/components/schemas/IssueCredentialRecord" diff --git a/prism-agent/service/api/http/prism-agent-openapi-spec.yaml b/prism-agent/service/api/http/prism-agent-openapi-spec.yaml index c9dbd08aff..9966e9cd13 100644 --- a/prism-agent/service/api/http/prism-agent-openapi-spec.yaml +++ b/prism-agent/service/api/http/prism-agent-openapi-spec.yaml @@ -554,9 +554,9 @@ paths: post: tags: ["Issue Credentials Protocol"] operationId: createCredentialOffer - summary: As a VC issuer, create a new credential offer to be sent to a VC holder + summary: As a credential issuer, create a new credential offer to be sent to a holder. requestBody: - description: CredentialOffer object with schema identifier and claims + description: The credential offer object. required: true content: application/json: @@ -564,13 +564,13 @@ paths: $ref: ./pollux/schemas.yaml#/components/schemas/CreateIssueCredentialRecordRequest responses: "201": - description: The issue credential record + description: The issue credential record was created successfully, and is returned in the response body. content: application/json: schema: $ref: ./pollux/schemas.yaml#/components/schemas/IssueCredentialRecord "422": - description: The issue credential record creation failed. + description: The issue credential record creation failed. More information on the error can be found in the response body. content: application/json: schema: @@ -580,16 +580,16 @@ paths: get: tags: ["Issue Credentials Protocol"] operationId: getCredentialRecords - summary: Get credential records + summary: Gets the list of issue credential records. responses: "200": - description: The issue credential records + description: The list of issue credential records. content: application/json: schema: $ref: ./pollux/schemas.yaml#/components/schemas/IssueCredentialRecordCollection "500": - description: Retrieving the issue credential records failed for an unexpected reason. + description: Retrieving the issue credential records failed for an unexpected reason. More information on the error can be found in the response body. content: application/json: schema: @@ -599,18 +599,18 @@ paths: get: tags: ["Issue Credentials Protocol"] operationId: getCredentialRecord - summary: Get a credential record by Id + summary: Gets an existing issue credential record by its unique identifier. parameters: - $ref: ./pollux/parameters.yaml#/components/parameters/issueCredentialRecordIdInPath responses: "200": - description: The issue credential record + description: The issue credential record. content: application/json: schema: $ref: ./pollux/schemas.yaml#/components/schemas/IssueCredentialRecord "404": - description: There is no issue credential record matching the given 'recordId'. + description: There is no issue credential record matching the given identifier. content: application/json: schema: @@ -620,18 +620,19 @@ paths: post: tags: ["Issue Credentials Protocol"] operationId: acceptCredentialOffer - summary: As a VC holder, accept a credential offer received from an issuer + summary: As a holder, accepts a credential offer received from an issuer. + description: Accepts a credential offer received from a VC issuer and sends back a credential request. parameters: - $ref: ./pollux/parameters.yaml#/components/parameters/issueCredentialRecordIdInPath responses: "200": - description: The issue credential offer has been accepted + description: The issue credential offer was successfully accepted. content: application/json: schema: $ref: ./pollux/schemas.yaml#/components/schemas/IssueCredentialRecord "404": - description: There is no issue credential record matching the given 'recordId'. + description: There is no issue credential record matching the given identifier. content: application/json: schema: @@ -641,18 +642,18 @@ paths: post: tags: ["Issue Credentials Protocol"] operationId: issueCredential - summary: As a VC issuer, issue the VC for the specified issue credential record + summary: As an issuer, issues the verifiable credential related to the specified record. parameters: - $ref: ./pollux/parameters.yaml#/components/parameters/issueCredentialRecordIdInPath responses: "200": - description: The VC has been issued + description: The request was processed successfully and the credential will be issued asynchronously. content: application/json: schema: $ref: ./pollux/schemas.yaml#/components/schemas/IssueCredentialRecord "404": - description: There is no issue credential record matching the given 'recordId'. + description: There is no issue credential record matching the given identifier. content: application/json: schema: @@ -829,7 +830,7 @@ paths: post: tags: ["Connections Management"] operationId: createConnection - summary: Creates a new connection record and returns an Out of Band invitation + summary: Creates a new connection record and returns an Out of Band invitation. description: | Generates a new Peer DID and creates an [Out of Band 2.0](https://identity.foundation/didcomm-messaging/spec/v2.0/#out-of-band-messages) invitation. It returns a new connection record in `InvitationGenerated` state. @@ -843,13 +844,13 @@ paths: responses: "201": - description: The connection record + description: The connection record was created successfully, and is returned in the response body. content: application/json: schema: $ref: "./connect/schemas.yaml#/components/schemas/Connection" "422": - description: The connection record creation failed. + description: The connection record creation failed. More information on the error can be found in the response body. content: application/json: schema: @@ -858,16 +859,16 @@ paths: get: tags: ["Connections Management"] operationId: getConnections - summary: Returns the list of connection records + summary: Gets the list of connection records. responses: "200": - description: List of connection records + description: The list of connection records. content: application/json: schema: $ref: "./connect/schemas.yaml#/components/schemas/ConnectionCollection" "500": - description: Retrieving the connection records failed for an unexpected reason. + description: Retrieving the connection records failed for an unexpected reason. More information on the error can be found in the response body. content: application/json: schema: @@ -879,16 +880,16 @@ paths: parameters: - $ref: "./connect/schemas.yaml#/components/parameters/connectionId" operationId: getConnection - summary: Returns an existing connection record by its Id + summary: Gets an existing connection record by its unique identifier. responses: "200": - description: Connection state record + description: The connection record. content: application/json: schema: $ref: "./connect/schemas.yaml#/components/schemas/Connection" "404": - description: There is no issue credential record matching the given 'recordId'. + description: There is no connection record matching the given identifier. content: application/json: schema: @@ -898,7 +899,7 @@ paths: post: tags: ["Connections Management"] operationId: acceptConnectionInvitation - summary: Accepts an Out of Band invitation + summary: Accepts an Out of Band invitation. description: | Accepts an [Out of Band 2.0](https://identity.foundation/didcomm-messaging/spec/v2.0/#out-of-band-messages) invitation, generates a new Peer DID, and submits a Connection Request to the inviter. @@ -912,13 +913,13 @@ paths: responses: "200": - description: Invitation successfully accepted. + description: The invitation was successfully accepted. content: application/json: schema: $ref: "./connect/schemas.yaml#/components/schemas/Connection" "500": - description: Storing the connection invitation failed for an unexpected reason. + description: Storing the connection invitation failed for an unexpected reason. More information on the error can be found in the response body. content: application/json: schema: