From 10f055057a78b4dd3821ee88552d46ab28305f94 Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Fri, 10 Mar 2023 13:50:09 +0100 Subject: [PATCH 01/11] docs: add webhooks openapi spec --- packages/backend/src/openapi/webhooks.yaml | 275 +++++++++++++++++++++ 1 file changed, 275 insertions(+) create mode 100644 packages/backend/src/openapi/webhooks.yaml diff --git a/packages/backend/src/openapi/webhooks.yaml b/packages/backend/src/openapi/webhooks.yaml new file mode 100644 index 0000000000..ab87e87739 --- /dev/null +++ b/packages/backend/src/openapi/webhooks.yaml @@ -0,0 +1,275 @@ +openapi: 3.1.0 +info: + title: Rafiki Webhooks + version: 1.0.0 +webhooks: + incomingPaymentCompleted: + post: + requestBody: + description: Notify account servicing entity that an incoming payment was completed and funds should now be withdrawn. + content: + application/json: + schema: + $ref: '#/components/schemas/incomingPayment' + responses: + '200': + description: Return a 200 status to indicate that the data was received successfully + incomingPaymentExpired: + post: + requestBody: + description: Notify account servicing entity that an incoming payment has expired and funds should now be withdrawn. + content: + application/json: + schema: + $ref: '#/components/schemas/incomingPayment' + responses: + '200': + description: Return a 200 status to indicate that the data was received successfully + outgoingPaymentCreated: + post: + requestBody: + description: Notify account servicing entity that an outgoing payment was created and should now be funded. + content: + application/json: + schema: + $ref: '#/components/schemas/outgoingPayment' + responses: + '200': + description: Return a 200 status to indicate that the data was received successfully + outgoingPaymentCompleted: + post: + requestBody: + description: Notify account servicing entity that an outgoing payment completed. Remaining funds should be withdrawn. + content: + application/json: + schema: + $ref: '#/components/schemas/outgoingPayment' + responses: + '200': + description: Return a 200 status to indicate that the 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. + content: + application/json: + schema: + $ref: '#/components/schemas/outgoingPayment' + responses: + '200': + description: Return a 200 status to indicate that the data was received successfully + webMonetization: + post: + requestBody: + description: Notify account servicing entity that a Web Monetization payment was received and funds should be withdrawn. + content: + application/json: + schema: + $ref: '#/components/schemas/webMonetization' + responses: + '200': + description: Return a 200 status to indicate that the data was received successfully + +components: + schemas: + incomingPayment: + required: + - id + - type + - attempts + - processAt + - data + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - incoming_payment.completed + - incoming_payment.expired + attempts: + type: integer + processAt: + type: string + format: date-time + data: + type: object + required: + - id + - paymentPointerId + - createdAt + - updatedAt + - expiresAt + - receivedAmount + - completed + properties: + id: + type: string + format: uuid + paymentPointerId: + type: string + format: uuid + completed: + type: boolean + incomingAmount: + $ref: ./schemas.yaml#/components/schemas/amount + receivedAmount: + $ref: ./schemas.yaml#/components/schemas/amount + description: + type: string + externalRef: + type: string + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + expiresAt: + type: string + format: date-time + statusCode: + type: integer + withdrawal: + $ref: '#/components/schemas/withdrawal' + outgoingPayment: + required: + - id + - type + - attempts + - processAt + - data + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - outgoing_payment.created + - outgoing_payment.completed + - outgoing_payment.failed + attempts: + type: integer + processAt: + type: string + format: date-time + data: + type: object + required: + - id + - paymentPointerId + - createdAt + - updatedAt + - expiresAt + - sendAmount + - receiveAmount + - state + - stateAttempts + - balance + properties: + id: + type: string + format: uuid + paymentPointerId: + type: string + format: uuid + state: + type: string + enum: + - FUNDING + - SENDING + - FAILED + - COMPLETED + sendAmount: + $ref: ./schemas.yaml#/components/schemas/amount + sentAmount: + $ref: ./schemas.yaml#/components/schemas/amount + description: + type: string + externalRef: + type: string + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + expiresAt: + type: string + format: date-time + error: + type: string + stateAttempts: + type: integer + balance: + type: string + format: uint64 + peerId: + type: string + format: uuid + statusCode: + type: integer + withdrawal: + $ref: '#/components/schemas/withdrawal' + webMonetization: + required: + - id + - type + - attempts + - processAt + - data + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - payment_pointer.web_monetization + attempts: + type: integer + processAt: + type: string + format: date-time + data: + type: object + required: + - paymentPointer + properties: + paymentPointer: + type: object + required: + - id + - createdAt + - received + properties: + id: + type: string + format: uuid + createdAt: + type: string + format: date-time + received: + type: string + format: uint64 + statusCode: + type: integer + withdrawal: + $ref: '#/components/schemas/withdrawal' + withdrawal: + type: object + required: + - accountId: string + - assetId: string + - amount: bigint + properties: + accountId: + type: string + format: uuid + assetId: + type: string + format: uuid + amount: + type: integer \ No newline at end of file From aca512dcd6409cae5967bab2c7203b85520713d2 Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Fri, 10 Mar 2023 13:57:36 +0100 Subject: [PATCH 02/11] fix: formatting --- packages/backend/src/openapi/webhooks.yaml | 84 +++++++++++----------- 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/packages/backend/src/openapi/webhooks.yaml b/packages/backend/src/openapi/webhooks.yaml index ab87e87739..8b8d062136 100644 --- a/packages/backend/src/openapi/webhooks.yaml +++ b/packages/backend/src/openapi/webhooks.yaml @@ -84,16 +84,16 @@ components: type: string format: uuid type: - type: string - enum: - - incoming_payment.completed - - incoming_payment.expired + type: string + enum: + - incoming_payment.completed + - incoming_payment.expired attempts: type: integer processAt: type: string format: date-time - data: + data: type: object required: - id @@ -104,29 +104,29 @@ components: - receivedAmount - completed properties: - id: + id: type: string format: uuid - paymentPointerId: + paymentPointerId: type: string format: uuid completed: type: boolean - incomingAmount: + incomingAmount: $ref: ./schemas.yaml#/components/schemas/amount - receivedAmount: + receivedAmount: $ref: ./schemas.yaml#/components/schemas/amount - description: + description: type: string - externalRef: + externalRef: type: string - createdAt: + createdAt: type: string format: date-time - updatedAt: + updatedAt: type: string format: date-time - expiresAt: + expiresAt: type: string format: date-time statusCode: @@ -145,17 +145,17 @@ components: type: string format: uuid type: - type: string - enum: - - outgoing_payment.created - - outgoing_payment.completed - - outgoing_payment.failed + type: string + enum: + - outgoing_payment.created + - outgoing_payment.completed + - outgoing_payment.failed attempts: type: integer processAt: type: string format: date-time - data: + data: type: object required: - id @@ -169,10 +169,10 @@ components: - stateAttempts - balance properties: - id: + id: type: string format: uuid - paymentPointerId: + paymentPointerId: type: string format: uuid state: @@ -182,31 +182,31 @@ components: - SENDING - FAILED - COMPLETED - sendAmount: + sendAmount: $ref: ./schemas.yaml#/components/schemas/amount - sentAmount: + sentAmount: $ref: ./schemas.yaml#/components/schemas/amount - description: + description: type: string - externalRef: + externalRef: type: string - createdAt: + createdAt: type: string format: date-time - updatedAt: + updatedAt: type: string format: date-time - expiresAt: + expiresAt: type: string format: date-time - error: + error: type: string - stateAttempts: + stateAttempts: type: integer - balance: + balance: type: string format: uint64 - peerId: + peerId: type: string format: uuid statusCode: @@ -225,15 +225,15 @@ components: type: string format: uuid type: - type: string - enum: - - payment_pointer.web_monetization + type: string + enum: + - payment_pointer.web_monetization attempts: type: integer processAt: type: string format: date-time - data: + data: type: object required: - paymentPointer @@ -245,13 +245,13 @@ components: - createdAt - received properties: - id: + id: type: string format: uuid - createdAt: + createdAt: type: string format: date-time - received: + received: type: string format: uint64 statusCode: @@ -271,5 +271,5 @@ components: assetId: type: string format: uuid - amount: - type: integer \ No newline at end of file + amount: + type: integer From 6d1091cdd4f498615313c3747453710b15bbd3d6 Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Mon, 13 Mar 2023 13:21:26 +0100 Subject: [PATCH 03/11] chore: add open api validation action --- .github/workflows/validate-openapi.yml | 38 ++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 .github/workflows/validate-openapi.yml diff --git a/.github/workflows/validate-openapi.yml b/.github/workflows/validate-openapi.yml new file mode 100644 index 0000000000..118d3d4a2b --- /dev/null +++ b/.github/workflows/validate-openapi.yml @@ -0,0 +1,38 @@ +name: OpenAPI Validator + +on: + push: + branches: + - main + paths: + - packages/auth/src/openapi/** + - packages/backend/src/openapi/** + - packages/token-introspection/src/openapi/** + pull_request: + branches: + - main + paths: + - packages/auth/src/openapi/** + - packages/backend/src/openapi/** + - packages/token-introspection/src/openapi/** + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v2 + + - name: Lint Open API specs + run: | + npx prettier --check packages/auth/src/openapi/id-provider.yaml + npx prettier --check packages/backend/src/openapi/webhooks.yaml + npx prettier --check packages/token-introspection/src/openapi/token-introspection.yaml + - name: AsyncAPI extension + run: | + echo "{\"extends\":[\"spectral:oas\",\"spectral:asyncapi\"]}" >> .spectral.json + - name: Validate Open API specs + run: | + npx @stoplight/spectral-cli lint packages/auth/src/openapi/id-provider.yaml + npx @stoplight/spectral-cli lint packages/backend/src/openapi/webhooks.yaml + npx @stoplight/spectral-cli lint packages/token-introspection/src/openapi/token-introspection.yaml \ No newline at end of file From f4dabb6d9d4397134ab353d87b2477973610b90a Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Tue, 14 Mar 2023 12:51:17 +0100 Subject: [PATCH 04/11] docs(backend): add description and contact info --- packages/backend/src/openapi/webhooks.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/backend/src/openapi/webhooks.yaml b/packages/backend/src/openapi/webhooks.yaml index 8b8d062136..0a20588fab 100644 --- a/packages/backend/src/openapi/webhooks.yaml +++ b/packages/backend/src/openapi/webhooks.yaml @@ -2,6 +2,9 @@ openapi: 3.1.0 info: title: Rafiki Webhooks version: 1.0.0 + description: 'Webhook Events fired by Rafiki' + contact: + email: tech@interledger.org webhooks: incomingPaymentCompleted: post: From 4a58b7aa15901c891b4791fa7135a588db1d5546 Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Tue, 14 Mar 2023 12:53:21 +0100 Subject: [PATCH 05/11] style(backend): rename schemas --- packages/backend/src/openapi/webhooks.yaml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/packages/backend/src/openapi/webhooks.yaml b/packages/backend/src/openapi/webhooks.yaml index 0a20588fab..d865aca85a 100644 --- a/packages/backend/src/openapi/webhooks.yaml +++ b/packages/backend/src/openapi/webhooks.yaml @@ -13,7 +13,7 @@ webhooks: content: application/json: schema: - $ref: '#/components/schemas/incomingPayment' + $ref: '#/components/schemas/incomingPaymentEvent' responses: '200': description: Return a 200 status to indicate that the data was received successfully @@ -24,7 +24,7 @@ webhooks: content: application/json: schema: - $ref: '#/components/schemas/incomingPayment' + $ref: '#/components/schemas/incomingPaymentEvent' responses: '200': description: Return a 200 status to indicate that the data was received successfully @@ -35,7 +35,7 @@ webhooks: content: application/json: schema: - $ref: '#/components/schemas/outgoingPayment' + $ref: '#/components/schemas/outgoingPaymentEvent' responses: '200': description: Return a 200 status to indicate that the data was received successfully @@ -46,7 +46,7 @@ webhooks: content: application/json: schema: - $ref: '#/components/schemas/outgoingPayment' + $ref: '#/components/schemas/outgoingPaymentEvent' responses: '200': description: Return a 200 status to indicate that the data was received successfully @@ -57,7 +57,7 @@ webhooks: content: application/json: schema: - $ref: '#/components/schemas/outgoingPayment' + $ref: '#/components/schemas/outgoingPaymentEvent' responses: '200': description: Return a 200 status to indicate that the data was received successfully @@ -68,14 +68,14 @@ webhooks: content: application/json: schema: - $ref: '#/components/schemas/webMonetization' + $ref: '#/components/schemas/webMonetizationEvent' responses: '200': description: Return a 200 status to indicate that the data was received successfully components: schemas: - incomingPayment: + incomingPaymentEvent: required: - id - type @@ -136,7 +136,7 @@ components: type: integer withdrawal: $ref: '#/components/schemas/withdrawal' - outgoingPayment: + outgoingPaymentEvent: required: - id - type @@ -216,7 +216,7 @@ components: type: integer withdrawal: $ref: '#/components/schemas/withdrawal' - webMonetization: + webMonetizationEvent: required: - id - type From 32f53da42413c80f14ac8a0ed16d9124bc2a3236 Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Mon, 20 Mar 2023 09:14:45 +0200 Subject: [PATCH 06/11] fix(docs): remove non-required fields --- packages/backend/src/openapi/webhooks.yaml | 62 ++++++---------------- 1 file changed, 15 insertions(+), 47 deletions(-) diff --git a/packages/backend/src/openapi/webhooks.yaml b/packages/backend/src/openapi/webhooks.yaml index d865aca85a..45c391e90e 100644 --- a/packages/backend/src/openapi/webhooks.yaml +++ b/packages/backend/src/openapi/webhooks.yaml @@ -79,8 +79,6 @@ components: required: - id - type - - attempts - - processAt - data properties: id: @@ -91,11 +89,6 @@ components: enum: - incoming_payment.completed - incoming_payment.expired - attempts: - type: integer - processAt: - type: string - format: date-time data: type: object required: @@ -132,16 +125,10 @@ components: expiresAt: type: string format: date-time - statusCode: - type: integer - withdrawal: - $ref: '#/components/schemas/withdrawal' outgoingPaymentEvent: required: - id - type - - attempts - - processAt - data properties: id: @@ -153,11 +140,6 @@ components: - outgoing_payment.created - outgoing_payment.completed - outgoing_payment.failed - attempts: - type: integer - processAt: - type: string - format: date-time data: type: object required: @@ -212,16 +194,25 @@ components: peerId: type: string format: uuid - statusCode: - type: integer withdrawal: - $ref: '#/components/schemas/withdrawal' + type: object + required: + - accountId: string + - assetId: string + - amount: bigint + properties: + accountId: + type: string + format: uuid + assetId: + type: string + format: uuid + amount: + type: integer webMonetizationEvent: required: - id - type - - attempts - - processAt - data properties: id: @@ -231,11 +222,6 @@ components: type: string enum: - payment_pointer.web_monetization - attempts: - type: integer - processAt: - type: string - format: date-time data: type: object required: @@ -257,22 +243,4 @@ components: received: type: string format: uint64 - statusCode: - type: integer - withdrawal: - $ref: '#/components/schemas/withdrawal' - withdrawal: - type: object - required: - - accountId: string - - assetId: string - - amount: bigint - properties: - accountId: - type: string - format: uuid - assetId: - type: string - format: uuid - amount: - type: integer + From bc4f24f9ea4bbdc256987170dabd62f1ff0302cc Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Mon, 20 Mar 2023 09:16:13 +0200 Subject: [PATCH 07/11] fix: format --- packages/backend/src/openapi/webhooks.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/backend/src/openapi/webhooks.yaml b/packages/backend/src/openapi/webhooks.yaml index 45c391e90e..9c7f35ef74 100644 --- a/packages/backend/src/openapi/webhooks.yaml +++ b/packages/backend/src/openapi/webhooks.yaml @@ -243,4 +243,3 @@ components: received: type: string format: uint64 - From c6340517efc53b7c4d084e555e38813cb59fb1bb Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Mon, 20 Mar 2023 16:05:45 +0200 Subject: [PATCH 08/11] fix(docs): remove withdrawal --- packages/backend/src/openapi/webhooks.yaml | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/packages/backend/src/openapi/webhooks.yaml b/packages/backend/src/openapi/webhooks.yaml index 9c7f35ef74..a997e7cc70 100644 --- a/packages/backend/src/openapi/webhooks.yaml +++ b/packages/backend/src/openapi/webhooks.yaml @@ -194,21 +194,6 @@ components: peerId: type: string format: uuid - withdrawal: - type: object - required: - - accountId: string - - assetId: string - - amount: bigint - properties: - accountId: - type: string - format: uuid - assetId: - type: string - format: uuid - amount: - type: integer webMonetizationEvent: required: - id From 0c4eff7abce9fbf7e56582cba5bd4ddf42230bf7 Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Tue, 21 Mar 2023 09:37:52 +0200 Subject: [PATCH 09/11] fix(docs): add receiver to outgoing payment webhook event --- packages/backend/src/openapi/webhooks.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/backend/src/openapi/webhooks.yaml b/packages/backend/src/openapi/webhooks.yaml index a997e7cc70..06686e228b 100644 --- a/packages/backend/src/openapi/webhooks.yaml +++ b/packages/backend/src/openapi/webhooks.yaml @@ -153,6 +153,7 @@ components: - state - stateAttempts - balance + - receiver properties: id: type: string @@ -167,6 +168,9 @@ components: - SENDING - FAILED - COMPLETED + receiver: + type: string + format: uri sendAmount: $ref: ./schemas.yaml#/components/schemas/amount sentAmount: From 48525adfdc17f4b6e19a5bbed47f3fe786caed3e Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Tue, 21 Mar 2023 09:39:08 +0200 Subject: [PATCH 10/11] fix: format --- packages/backend/src/openapi/webhooks.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/backend/src/openapi/webhooks.yaml b/packages/backend/src/openapi/webhooks.yaml index 06686e228b..fd42ccc94d 100644 --- a/packages/backend/src/openapi/webhooks.yaml +++ b/packages/backend/src/openapi/webhooks.yaml @@ -168,7 +168,7 @@ components: - SENDING - FAILED - COMPLETED - receiver: + receiver: type: string format: uri sendAmount: From 1662a22f941fccbb8f42de45ee0bc6ad55e94b9f Mon Sep 17 00:00:00 2001 From: Sabine Schaller Date: Wed, 22 Mar 2023 09:13:10 +0200 Subject: [PATCH 11/11] fix(docs): add `additionalProperties: false` --- packages/backend/src/openapi/webhooks.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/backend/src/openapi/webhooks.yaml b/packages/backend/src/openapi/webhooks.yaml index fd42ccc94d..48cd647a96 100644 --- a/packages/backend/src/openapi/webhooks.yaml +++ b/packages/backend/src/openapi/webhooks.yaml @@ -125,6 +125,7 @@ components: expiresAt: type: string format: date-time + additionalProperties: false outgoingPaymentEvent: required: - id @@ -198,6 +199,7 @@ components: peerId: type: string format: uuid + additionalProperties: false webMonetizationEvent: required: - id @@ -232,3 +234,4 @@ components: received: type: string format: uint64 + additionalProperties: false