Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Initial GET and DELETE Operations #271

Merged
merged 18 commits into from
Mar 29, 2022
Merged

Initial GET and DELETE Operations #271

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
c68cb2b
feat: add initial bundling of api
mprorock Mar 13, 2022
2a53cae
feat: add stubs for common openapi ux
mprorock Mar 13, 2022
01db86f
chore: stub in api viewers
mprorock Mar 13, 2022
594fc5c
chore: update build script
mprorock Mar 13, 2022
50b20ea
chore: add initial tags
mprorock Mar 13, 2022
4298e47
chore: update bundling and outputs
mprorock Mar 13, 2022
cfe28f3
chore: specify dev dependencies
mprorock Mar 13, 2022
4adeeb1
feat: add gh workflow to build and deploy docs
mprorock Mar 13, 2022
19c3bff
doc: update readme for npm build
mprorock Mar 13, 2022
d0e5a31
chore: add initial holder getters for credentials and presentations
mprorock Mar 13, 2022
1041f1e
chore: add delete for creds and presos
mprorock Mar 13, 2022
ca74e07
chore: remove any auto-gen-files
mprorock Mar 13, 2022
9df6b57
chore: update gitignore for auto-gen files
mprorock Mar 13, 2022
baf487c
chore: merge from auto-gen removed files
mprorock Mar 13, 2022
e6990c8
chore: updates prior to merge
mprorock Mar 29, 2022
f871d1f
chore: merge upstream main and clean up tags
mprorock Mar 29, 2022
6dc46c9
chore: update to use ref to object id rather than uuid
mprorock Mar 29, 2022
bc57899
chore: remove autogen files
mprorock Mar 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ This entails:

### Development

To assemble bundled yamls, as well as a all-in-one bundle of all definitions
To assemble bundled yamls, as well as an all-in-one bundle of all definitions
run the following:

```bash
Expand Down
15 changes: 15 additions & 0 deletions components/parameters/path/ObjectId.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
in: path
name: object-id
required: true
schema:
anyOf:
- 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}"
- type: string
pattern: "z[1-9A-HJ-NP-Za-km-z]{21,22}"
- type: string
pattern: "u[a-zA-Z0-9_-]{22,23}"
example:
- f37e5114-8b4a-11ec-b32e-fbd62b9502c1
- z4Z1T4HdLdfXCFAhdhzdCqm
- u7m8_ybOArX-EWeADqWCsIw
186 changes: 182 additions & 4 deletions holder.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,98 @@ info:
name: GitHub Source Code
url: https://github.com/w3c-ccg/vc-api
paths:
/credentials/{id}:
get:
tags:
- Credentials
summary: Gets a credential or verifiable credential by ID
operationId: getCredential
parameters:
- $ref: "./components/parameters/path/ObjectId.yml"
responses:
"200":
description: Credential retrieved
content:
application/json:
schema:
oneOf:
- $ref: "./components/Credential.yml#/components/schemas/Credential"
- $ref: "./components/VerifiableCredential.yml#/components/schemas/VerifiableCredential"
"400":
description: Bad Request
"401":
description: Not Authorized
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are we going to define authorization? and test it?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are we going to define authorization? and test it?

The test suites will need to have some authz mechanism in them because the production software that all implementers are implementing are all (AFAIK) requiring authz. If we have interop on the test suites, the spec will have to reflect reality and document how authz is being performed in an interoperable fashion.

"410":
description: Gone! There is no data here
"418":
description: I'm a teapot - MUST not be returned outside of pre-arranged scenarios between both parties
Comment on lines +36 to +37
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Har har :) -- presuming we're going to eventually remove this... because if we don't, we'll have to test for it.

"500":
description: Internal Error
"501":
description: Not Implemented
delete:
tags:
- Credentials
summary: Deletes a credential or verifiable credential by ID
operationId: deleteCredential
parameters:
- $ref: "./components/parameters/path/ObjectId.yml"
responses:
"202":
description: Credential deleted - this is a 202 by default as soft deletes and processing time are assumed
Copy link
Contributor

@msporny msporny Mar 29, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should probably say "Credential marked for deletion". Looks like the proposal here is that this call is sometimes implemented as eventually consistent. This also need to state what the side effects are... like, if associated with a status list, what happens to the status bits?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#276

"400":
description: Bad Request
"401":
description: Not Authorized
"410":
description: Gone! There is no data here
"500":
description: Internal Error
"501":
description: Not Implemented
/credentials:
get:
tags:
- Credentials
summary: Gets list of credentials or verifiable credentials
operationId: getCredentials
parameters:
- in: query
name: type
schema:
type: array
items:
type: string
oneOf:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These options seem a bit arbitrary... fine for now, but we need to define exactly what should be happening when each option is provided... for example, is this really checking the type field, or is it doing something else -- my guess is the latter... while the former might be more useful?

- "credentials"
- "verifiablecredentials"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- "verifiablecredentials"
- "verifiable-credentials"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why kebab-case instead of camelCase? We're using camelCase everywhere else, no?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

its a query string param, and its pluralized... so i figured it would be better to not have it look like verifiableCredential which shows up in VPs, but I am not attached to anything other than fixing the lowercase concatenation issue.

Copy link
Contributor

@msporny msporny Mar 29, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the explanation, I didn't see that it was a query param, I agree with your view wrt. casing and query params.

- "all"
responses:
"200":
description: Credentials retrieved
content:
application/json:
schema:
type: array
description: The Credentials
items:
anyOf:
- $ref: "./components/VerifiableCredential.yml#/components/schemas/VerifiableCredential"
- $ref: "./components/Credential.yml#/components/schemas/Credential"
"400":
description: Bad Request
"401":
description: Not Authorized
"410":
description: Gone! There is no data here
"500":
description: Internal Error
"501":
description: Not Implemented
/credentials/derive:
post:
tags:
- credential
- Credentials
summary: Derives a credential and returns it in the response body.
operationId: deriveCredential
description: Derives a credential and returns it in the response body.
Expand All @@ -36,11 +124,99 @@ paths:
description: Internal Error
"501":
description: Not Implemented

/presentations/{id}:
get:
tags:
- Presentations
summary: Gets a presentation or verifiable presentation by ID
operationId: getPresentation
parameters:
- $ref: "./components/parameters/path/ObjectId.yml"
responses:
"200":
description: Credential retrieved
content:
application/json:
schema:
oneOf:
- $ref: "./components/Presentation.yml#/components/schemas/Presentation"
- $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation"
"400":
description: Bad Request
"401":
description: Not Authorized
"410":
description: Gone! There is no data here
"500":
description: Internal Error
"501":
description: Not Implemented
delete:
tags:
- Presentations
summary: Deletes a presentation or verifiable presentation by ID
operationId: deletePresentation
parameters:
- $ref: "./components/parameters/path/ObjectId.yml"
responses:
"202":
description: Presentation deleted - this is a 202 by default as soft deletes and processing time are assumed
"400":
description: Bad Request
"401":
description: Not Authorized
"410":
description: Gone! There is no data here
"500":
description: Internal Error
"501":
description: Not Implemented
/Presentation:
get:
tags:
- Presentations
summary: Gets list of presentations or verifiable presentations
operationId: getPresentations
parameters:
- in: query
name: type
schema:
type: array
items:
type: string
oneOf:
- "presentations"
- "verifiablepresentations"
- "all"
responses:
"200":
description: Presentations retrieved
content:
application/json:
schema:
type: array
description: The Presentations
items:
anyOf:
- $ref: "./components/Presentation.yml#/components/schemas/Presentation"
- $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation"
"400":
description: Bad Request
"401":
description: Not Authorized
"410":
description: Gone! There is no data here
"500":
description: Internal Error
"501":
description: Not Implemented

/presentations/prove:
post:
summary: Proves a presentation and returns it in the response body.
tags:
- presentation
- Presentations
operationId: provePresentation
description: Proves a presentation and returns it in the response body.
requestBody:
Expand All @@ -60,11 +236,12 @@ paths:
description: invalid input!
"500":
description: error!

/exchanges/{exchange-id}:
post:
summary: Initiates an exchange of information.
tags:
- exchange
- Exchanges
operationId: initiateExchange
description:
A client can use this endpoint to initiate an exchange of a particular
Expand Down Expand Up @@ -110,7 +287,7 @@ paths:
put:
summary: Receives information related to an existing exchange.
tags:
- exchange
- Exchanges
operationId: receiveExchangeData
description:
A client can use this endpoint to continue the exchange of information
Expand Down Expand Up @@ -143,6 +320,7 @@ paths:
description: Internal server error.
"501":
description: Service not implemented.

components:
schemas:
DeriveCredentialRequest:
Expand Down
4 changes: 2 additions & 2 deletions issuer.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ paths:
post:
summary: Issues a credential and returns it in the response body.
tags:
- credential
- Credentials
operationId: issueCredential
description: Issues a credential and returns it in the response body.
requestBody:
Expand All @@ -38,7 +38,7 @@ paths:
post:
summary: Updates the status of an issued credential
tags:
- credential
- Credentials
operationId: updateCredentialStatus
description: Updates the status of an issued credential.
requestBody:
Expand Down
4 changes: 2 additions & 2 deletions verifier.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ paths:
post:
summary: Verifies a verifiableCredential and returns a verificationResult in the response body.
tags:
- credential
- Credentials
operationId: verifyCredential
description: Verifies a verifiableCredential and returns a verificationResult in the response body.
requestBody:
Expand All @@ -38,7 +38,7 @@ paths:
post:
summary: Verifies a Presentation with or without proofs attached and returns a verificationResult in the response body.
tags:
- presentation
- Presentations
operationId: verifyPresentation
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:
Expand Down