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

docs: fixes 3084 #3088

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: fixes 3084 #3088

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
30 changes: 15 additions & 15 deletions packages/auth/src/openapi/specs/id-provider.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ info:
name: Apache 2.0
identifier: Apache-2.0
summary: Rafiki Authorization Server - Identity Provider Connection
description: 'The Open Payments API is secured via [GNAP](https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol). This specification describes the connection between the Rafiki Open Payments Authorization Server and an Identity Provider.'
description: 'The Open Payments APIs are secured via [GNAP](https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol). This specification describes the interaction endpoints used between a Rafiki Open Payments authorization server and an identity provider.'
contact:
email: [email protected]
servers:
- url: 'https://openpayments.guide/auth'
- url: 'https://openpayments.dev/auth'
tags:
- name: front-channel
description: Redirect URLs
Expand All @@ -19,7 +19,7 @@ tags:
paths:
'/interact/{id}/{nonce}':
get:
summary: Start user interaction
summary: Start user interaction session
responses:
'302':
content:
Expand Down Expand Up @@ -52,7 +52,7 @@ paths:
in: path
name: nonce
required: true
description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.'
description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI. Must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.'
- schema:
type: string
name: clientName
Expand All @@ -65,7 +65,7 @@ paths:
in: query
required: true
description: 'URI of the client that created the grant'
description: 'To start the user interaction for grant approval, this endpoint redirects the user to an Identity provider endpoint for authentication.'
description: 'This endpoint is called by the client to start the user interaction session for grant approval. The endpoint redirects the user to an identity provider endpoint for authentication.'
tags:
- front-channel
'/interact/{id}/{nonce}/finish':
Expand All @@ -91,7 +91,7 @@ paths:
description: Unauthorized
'404':
description: Not Found
description: "To finish the user interaction for grant approval, this endpoint redirects the user to the client's finish url."
description: "This endpoint is called by the identity provider to end the user interaction and redirect the user to the client's finish URL."
parameters:
- schema:
type: string
Expand All @@ -104,12 +104,12 @@ paths:
in: path
name: nonce
required: true
description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.'
description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI. Must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.'
tags:
- front-channel
'/grant/{id}/{nonce}':
get:
summary: Lookup Grant
summary: Look up grant information
responses:
'200':
description: OK
Expand All @@ -123,9 +123,9 @@ paths:
state:
description: |-
Interaction state:
* `PENDING` - Awaiting interaction from resource owner (RO)
* `APPROVED` - RO approved interaction
* `DENIED` - RO Rejected interaction
* `PENDING` - Awaiting interaction from resource owner
* `APPROVED` - Resource owner approved interaction
* `DENIED` - Resource owner rejected interaction
type: string
enum:
- PENDING
Expand All @@ -140,7 +140,7 @@ paths:
description: Not Found
operationId: get-grant
description: |
The Identity Provider uses this endpoint to requests the grant details associated with the provided `interactId` on the front-channel. It will then display those details to the user to either accept or deny the grant.
This endpoint is called by the identity provider to get the grant details associated with the `interactId` on the front-channel. The identity provider will display the details to the user to either accept or deny.
parameters:
- schema:
type: string
Expand All @@ -153,7 +153,7 @@ paths:
in: path
name: nonce
required: true
description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.'
description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI. Must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.'
tags:
- back-channel
'/grant/{id}/{nonce}/{choice}':
Expand All @@ -169,7 +169,7 @@ paths:
description: Unauthorized
'404':
description: Not Found
description: The Identity Provider uses this endpoint to submit the user's choice regarding accepting or rejecting a grant to Authorization Server.
description: This endpoint is called by the identity provider to communicate the user's choice (acceptance or rejection) to the authorization server.
parameters:
- schema:
type: string
Expand All @@ -182,7 +182,7 @@ paths:
in: path
name: nonce
required: true
description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.'
description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI. Must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.'
- schema:
type: string
enum:
Expand Down
46 changes: 23 additions & 23 deletions packages/backend/src/openapi/specs/webhooks.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ openapi: 3.1.0
info:
title: Rafiki Webhooks
version: 1.1.0
description: 'Webhook Events fired by Rafiki'
description: 'Webhook events fired by Rafiki'
contact:
email: [email protected]
servers:
Expand All @@ -11,113 +11,113 @@ webhooks:
incomingPaymentCreated:
post:
requestBody:
description: Notify account servicing entity that an incoming payment was created.
description: Notifies the account servicing entity that an incoming payment was created. This event is purely informational.
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
description: Notifies the account servicing entity that an incoming payment was created. This event is purely informational.
description: Notifies the account servicing entity that an incoming payment was created.

we can actually optionally action incoming payments now via approveIncomingPayment and cancelIncomingPayment, so we can leave out the informational bit

content:
application/json:
schema:
$ref: '#/components/schemas/incomingPaymentEvent'
responses:
'200':
description: Returns a 200 status to indicate that the data was received successfully.
description: Data received successfully
incomingPaymentCompleted:
post:
requestBody:
description: Notify account servicing entity that an incoming payment was completed and funds should now be withdrawn.
description: Notifies the account servicing entity that an incoming payment was completed and funds should be withdrawn.
content:
application/json:
schema:
$ref: '#/components/schemas/incomingPaymentEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
incomingPaymentExpired:
post:
requestBody:
description: Notify account servicing entity that an incoming payment has expired and funds should now be withdrawn.
description: Notifies the account servicing entity that an incoming payment has expired and funds should be withdrawn.
content:
application/json:
schema:
$ref: '#/components/schemas/incomingPaymentEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
outgoingPaymentCreated:
post:
requestBody:
description: Notify account servicing entity that an outgoing payment was created and should now be funded.
description: Notifies the account servicing entity that an outgoing payment was created and is awaiting funding.
content:
application/json:
schema:
$ref: '#/components/schemas/outgoingPaymentEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
outgoingPaymentCompleted:
post:
requestBody:
description: Notify account servicing entity that an outgoing payment completed. Remaining funds should be withdrawn.
description: Notifies the account servicing entity that an outgoing payment completed and any remaining funds should be withdrawn.
content:
application/json:
schema:
$ref: '#/components/schemas/outgoingPaymentEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
outgoingPaymentFailed:
post:
requestBody:
description: Notify account servicing entity that an outgoing payment failed and won't be retried. Funds should be withdrawn.
description: Notifies the account servicing entity that an outgoing payment failed, the retry was unsuccessful, and funds should be withdrawn.
content:
application/json:
schema:
$ref: '#/components/schemas/outgoingPaymentEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
walletAddressNotFound:
post:
requestBody:
description: Notify account servicing entity to create a wallet address if it can find a corresponding account in their system.
description: Notifies the account servicing entity to create a wallet address for the associated account in their system.
content:
application/json:
schema:
$ref: '#/components/schemas/walletAddressNotFound'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
webMonetization:
post:
requestBody:
description: Notify account servicing entity that a Web Monetization payment was received and funds should be withdrawn.
description: Notifies the account servicing entity that a Web Monetization payment was received and funds should be withdrawn.
content:
application/json:
schema:
$ref: '#/components/schemas/webMonetizationEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
assetLiquidity:
post:
requestBody:
description: Notify account servicing entity that asset liquidity is low.
description: Notifies the account servicing entity that the liquidity for a specific asset is low.
content:
application/json:
schema:
$ref: '#/components/schemas/liquidityEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
peerLiquidity:
post:
requestBody:
description: Notify account servicing entity that peer liquidity is low.
description: Notifies the account servicing entity that the liquidity for a specific peer is low.
content:
application/json:
schema:
$ref: '#/components/schemas/liquidityEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully

components:
schemas:
Expand Down Expand Up @@ -358,10 +358,10 @@ components:
value:
type: string
format: uint64
description: 'The value is an unsigned 64-bit integer amount, represented as a string.'
description: 'An unsigned 64-bit integer amount, represented as a string.'
assetCode:
type: string
description: The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.
description: A code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.
Copy link
Contributor

Choose a reason for hiding this comment

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

Maybe we can mention that it should be an ISO4217 if possible. Kind of like we have in the docs page for assets:

"The asset code, generally an ISO 4217 currency code where available."

assetScale:
type: integer
minimum: 0
Expand Down
Loading
Loading