From d29e1c5049af0fa71e64d1567c93b613ff59c201 Mon Sep 17 00:00:00 2001 From: Pranav Kakaraparti Date: Wed, 30 Aug 2023 23:50:05 -0500 Subject: [PATCH 01/12] feat: /auth --- docs/api/spec/treetracker-token-api.yaml | 79 ++++++++++++++++++++---- 1 file changed, 67 insertions(+), 12 deletions(-) diff --git a/docs/api/spec/treetracker-token-api.yaml b/docs/api/spec/treetracker-token-api.yaml index 6ddc7267..e6c7cf66 100644 --- a/docs/api/spec/treetracker-token-api.yaml +++ b/docs/api/spec/treetracker-token-api.yaml @@ -1,8 +1,8 @@ openapi: 3.0.0 info: - title: treetracker token api + title: Treetracker Wallet API contact: {} - version: '0.9' + version: '1.10.3' paths: /auth: post: @@ -14,28 +14,57 @@ paths: - $ref: '#/components/parameters/treetrackerApiKeyParam' - $ref: '#/components/parameters/contentTypeJsonHeader' requestBody: - description: '' + description: 'Authentication request body' content: application/json: schema: - $ref: '#/components/schemas/authrequest' + $ref: '#/components/schemas/authRequest' examples: ById: value: - wallet: 1 + wallet: 21af8154-b7f1-48d3-8520-2e376efae45e password: walnut ByName: value: - wallet: zaven + wallet: wallet1 password: walnut required: true responses: '200': - description: '' + description: 'Successful authentication response' content: application/json: schema: $ref: '#/components/schemas/bearerToken' + '401': + description: 'Incorrect password for wallet' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 401 + message: 'Invalid Credentials' + '404': + description: 'No wallet found with provided wallet name or id' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 404 + message: 'Could not find entity by wallet name: bad_wallet' + '415': + $ref: '#/components/responses/UnsupportedMediaTypeError' + '422': + description: 'Missing request parameters' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"wallet" is not allowed to be empty' deprecated: false /tokens: get: @@ -751,7 +780,7 @@ components: type: string example: application/json schemas: - authrequest: + authRequest: title: Authentication Request required: - wallet @@ -761,18 +790,21 @@ components: wallet: oneOf: - type: string - - type: number + example: wallet1 + - type: string + format: uuid + example: 21af8154-b7f1-48d3-8520-2e376efae45e password: type: string - example: - wallet: zaven - password: walnut + example: walnut bearerToken: title: Successful Authentication Response type: object properties: bearer: type: string + example: + bearer: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... tokens: title: Token query response type: object @@ -1111,11 +1143,34 @@ components: type: string created_at: type: string + walletNameOrId: + oneOf: + - type: string + example: wallet1 + - type: string + format: uuid + example: bc7d4c0d-1ea5-4ead-9fef-b726a34c2d74 + errorResponse: + type: object + properties: + code: + type: integer + message: + type: string responses: UnauthorizedError: description: Access bearer token is missing or invalid ForbiddenError: description: Access denied for that resource + UnsupportedMediaTypeError: + description: Invalid content type + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 415 + message: 'Invalid content type. API only supports application/json' securitySchemes: httpBearer: type: http From 3e11a6de7081c90cf5794a0a3b627aceb825430d Mon Sep 17 00:00:00 2001 From: Pranav Kakaraparti Date: Thu, 31 Aug 2023 01:56:15 -0500 Subject: [PATCH 02/12] feat: /tokens --- docs/api/spec/treetracker-token-api.yaml | 200 ++++++++++++++--------- 1 file changed, 127 insertions(+), 73 deletions(-) diff --git a/docs/api/spec/treetracker-token-api.yaml b/docs/api/spec/treetracker-token-api.yaml index e6c7cf66..0520dfe6 100644 --- a/docs/api/spec/treetracker-token-api.yaml +++ b/docs/api/spec/treetracker-token-api.yaml @@ -70,14 +70,13 @@ paths: get: tags: - Token details - summary: Get a list of tokens in the current wallet or managed wallets + summary: 'Get a list of tokens in the current wallet or managed wallets' description: 'Get a list of for tokens in the current wallet or managed wallets, matching certain parameters' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - - $ref: '#/components/parameters/contentTypeJsonHeader' - name: limit in: query - description: Number of items to return + description: 'Number of items to return' required: true style: form explode: true @@ -95,30 +94,32 @@ paths: type: integer format: int32 example: 10 - - name: matching_all_tags - description: An array of tags. Tokens returned by the endpoints must be attached to trees that have ALL of these tags assigned - in: query - schema: - type: array - items: - type: string - name: wallet - description: Wallet id or name can be specified if the authenticated wallet manages other wallets. The default is to return tokens matching the authenticated wallet + description: 'Wallet name can be specified if the authenticated wallet manages other wallets. The default is to return tokens matching the authenticated wallet' in: query schema: - oneOf: - - type: string - - type: number - example: zaven2 + type: string + example: wallet1 responses: '200': - description: '' + description: 'Returns list of tokens matching the input parameters' content: application/json: schema: $ref: '#/components/schemas/tokens' '401': $ref: '#/components/responses/UnauthorizedError' + '403': + $ref: '#/components/responses/ForbiddenError' + '422': + description: 'Missing request parameters' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"limit" is required' deprecated: false '/tokens/{token_uuid}': get: @@ -146,6 +147,50 @@ paths: '401': $ref: '#/components/responses/UnauthorizedError' deprecated: false + '/tokens/{token_uuid}/transactions': + get: + tags: + - Token details + summary: Get transaction history for a particular token + parameters: + - $ref: '#/components/parameters/treetrackerApiKeyParam' + - $ref: '#/components/parameters/contentTypeJsonHeader' + - name: token_uuid + in: path + description: '' + required: true + explode: true + schema: + type: string + example: e3cd6587-ff01-419b-b2c9-44ceed4dc749 + - name: limit + in: query + description: Number of items to return + required: true + style: form + explode: true + schema: + type: integer + format: int32 + example: 10 + - name: start + in: query + description: 'Where does the list start, 1 means start from the beginning of the list' + required: false + style: form + explode: true + schema: + type: integer + format: int32 + example: 10 + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/historyResponse' + deprecated: false /wallets: get: tags: @@ -330,50 +375,6 @@ paths: description: Return array of matching transfers '401': $ref: '#/components/responses/UnauthorizedError' - '/tokens/{token_uuid}/transactions': - get: - tags: - - Token details - summary: Get transaction history for a particular token - parameters: - - $ref: '#/components/parameters/treetrackerApiKeyParam' - - $ref: '#/components/parameters/contentTypeJsonHeader' - - name: token_uuid - in: path - description: '' - required: true - explode: true - schema: - type: string - example: e3cd6587-ff01-419b-b2c9-44ceed4dc749 - - name: limit - in: query - description: Number of items to return - required: true - style: form - explode: true - schema: - type: integer - format: int32 - example: 10 - - name: start - in: query - description: 'Where does the list start, 1 means start from the beginning of the list' - required: false - style: form - explode: true - schema: - type: integer - format: int32 - example: 10 - responses: - '200': - description: '' - content: - application/json: - schema: - $ref: '#/components/schemas/historyResponse' - deprecated: false '/transfers/{transfer_id}': get: tags: @@ -816,24 +817,77 @@ components: tokenItem: title: Token type: object - example: - token: d895cf1b-de4c-40ea-85c9-99540f2489a9 - map_url: 'http://test.treetracker.org/?treeid=156867' - image_url: 'https://treetracker-test.eu-central-1/2019.08.13.17.56.13_5f87e44c-1b90-4d15-8ab8-ae4e75f8a898_IMG_20190813_175243_67017802.jpg' - tree_captured_at: '+051586-06-14T15:10:00.000Z' - latitude: 37.77295869 - longitude: -122.1781304 - region: United States - bill_of_value: json properties: - token: + id: + type: string + format: uuid + example: 'ca1a99c3-9797-465d-8ee3-8dbd26a08faa' + capture_id: type: string - map: + format: uuid + example: '8df635f6-2df8-496f-93da-3060fc1e3180' + wallet_id: type: string - image: + format: uuid + example: 'c63da6b3-d7a3-444a-9ff0-10644036eccd' + transfer_pending: + type: boolean + example: false + transfer_pending_id: type: string - capture: + format: uuid + example: null + created_at: type: string + format: date-time + example: '2021-07-02T18:31:07.208Z' + updated_at: + type: string + format: date-time + example: '2021-07-02T18:31:07.208Z' + claim: + type: boolean + example: false + tokenItemWithLinks: + title: Single Token Item + type: object + properties: + id: + type: string + format: uuid + example: 'ca1a99c3-9797-465d-8ee3-8dbd26a08faa' + capture_id: + type: string + format: uuid + example: '8df635f6-2df8-496f-93da-3060fc1e3180' + wallet_id: + type: string + format: uuid + example: 'c63da6b3-d7a3-444a-9ff0-10644036eccd' + transfer_pending: + type: boolean + example: false + transfer_pending_id: + type: string + format: uuid + example: null + created_at: + type: string + format: date-time + example: '2021-07-02T18:31:07.208Z' + updated_at: + type: string + format: date-time + example: '2021-07-02T18:31:07.208Z' + claim: + type: boolean + example: false + links: + type: object + properties: + capture: + type: string + example: '/webmap/tree?uuid=8df635f6-2df8-496f-93da-3060fc1e3180' accountrequest: title: accountrequest required: From 090faadea930c30fa5e9f85d37ad7340df558e3b Mon Sep 17 00:00:00 2001 From: Pranav Kakaraparti Date: Thu, 31 Aug 2023 02:36:48 -0500 Subject: [PATCH 03/12] feat: /token/:id --- docs/api/spec/treetracker-token-api.yaml | 49 ++++++++++++++++++++---- 1 file changed, 42 insertions(+), 7 deletions(-) diff --git a/docs/api/spec/treetracker-token-api.yaml b/docs/api/spec/treetracker-token-api.yaml index 0520dfe6..be15c938 100644 --- a/docs/api/spec/treetracker-token-api.yaml +++ b/docs/api/spec/treetracker-token-api.yaml @@ -93,6 +93,7 @@ paths: schema: type: integer format: int32 + default: 1 example: 10 - name: wallet description: 'Wallet name can be specified if the authenticated wallet manages other wallets. The default is to return tokens matching the authenticated wallet' @@ -129,39 +130,50 @@ paths: description: 'Get details for one token in the current wallet or managed wallets, matching certain parameters' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - - $ref: '#/components/parameters/contentTypeJsonHeader' - name: token_uuid - description: '' + description: 'ID of specific token to retrieve' in: path required: true schema: type: string + format: uuid example: 496ffa8e-2fa2-488c-98e1-acf9b57c230b responses: '200': - description: '' + description: 'ID of specific token to retrieve' content: application/json: schema: - $ref: '#/components/schemas/tokenItem' + $ref: '#/components/schemas/tokenItemWithLinks' '401': $ref: '#/components/responses/UnauthorizedError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + description: 'No token found matching token_uuid' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 404 + message: 'cannot find token by id:a5fee1ec-31dd-4150-aae1-dfe423ee9fc7' deprecated: false '/tokens/{token_uuid}/transactions': get: tags: - Token details - summary: Get transaction history for a particular token + summary: 'Get transaction history for a particular token' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - - $ref: '#/components/parameters/contentTypeJsonHeader' - name: token_uuid in: path - description: '' + description: 'ID of specific token to retrieve' required: true explode: true schema: type: string + format: uuid example: e3cd6587-ff01-419b-b2c9-44ceed4dc749 - name: limit in: query @@ -182,6 +194,7 @@ paths: schema: type: integer format: int32 + default: 1 example: 10 responses: '200': @@ -190,6 +203,24 @@ paths: application/json: schema: $ref: '#/components/schemas/historyResponse' + '404': + description: 'No token found matching token_uuid' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 404 + message: 'cannot find token by id:a5fee1ec-31dd-4150-aae1-dfe423ee9fc7' + '422': + description: 'Missing request parameters' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"limit" is required' deprecated: false /wallets: get: @@ -218,6 +249,7 @@ paths: schema: type: integer format: int32 + default: 1 example: 10 - name: order_by in: query @@ -369,6 +401,7 @@ paths: schema: type: integer format: int32 + default: 1 example: 10 responses: '200': @@ -522,6 +555,7 @@ paths: schema: type: integer format: int32 + default: 1 example: 10 responses: '200': @@ -601,6 +635,7 @@ paths: schema: type: integer format: int32 + default: 1 example: 10 - name: state in: query From 306b1ccaf2f32a26112d6e2be51a425e5c7f4eaf Mon Sep 17 00:00:00 2001 From: Pranav Kakaraparti Date: Thu, 31 Aug 2023 03:01:40 -0500 Subject: [PATCH 04/12] feat: /token/:id/transactions --- docs/api/spec/treetracker-token-api.yaml | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/api/spec/treetracker-token-api.yaml b/docs/api/spec/treetracker-token-api.yaml index be15c938..0e043b6f 100644 --- a/docs/api/spec/treetracker-token-api.yaml +++ b/docs/api/spec/treetracker-token-api.yaml @@ -168,7 +168,7 @@ paths: - $ref: '#/components/parameters/treetrackerApiKeyParam' - name: token_uuid in: path - description: 'ID of specific token to retrieve' + description: 'ID of specific token to retrieve the transactions of' required: true explode: true schema: @@ -198,11 +198,15 @@ paths: example: 10 responses: '200': - description: '' + description: 'Return list of transactions associated with the token' content: application/json: schema: $ref: '#/components/schemas/historyResponse' + '401': + $ref: '#/components/responses/UnauthorizedError' + '403': + $ref: '#/components/responses/ForbiddenError' '404': description: 'No token found matching token_uuid' content: @@ -213,7 +217,7 @@ paths: code: 404 message: 'cannot find token by id:a5fee1ec-31dd-4150-aae1-dfe423ee9fc7' '422': - description: 'Missing request parameters' + description: 'Missing or invalid request or query parameters' content: application/json: schema: @@ -1171,12 +1175,14 @@ components: properties: token: type: string + format: uuid sender_wallet: type: string receiver_wallet: type: string processed_at: type: string + format: date-time example: token: e3cd6587-ff01-419b-b2c9-44ceed4dc749 sender_wallet: zaven From f18f3fc22332920d6555e65232eee0e211b59b13 Mon Sep 17 00:00:00 2001 From: Pranav Kakaraparti Date: Thu, 31 Aug 2023 03:30:42 -0500 Subject: [PATCH 05/12] feat: /wallets --- docs/api/spec/treetracker-token-api.yaml | 88 ++++++++++++++++++------ 1 file changed, 67 insertions(+), 21 deletions(-) diff --git a/docs/api/spec/treetracker-token-api.yaml b/docs/api/spec/treetracker-token-api.yaml index 0e043b6f..6fa4a08a 100644 --- a/docs/api/spec/treetracker-token-api.yaml +++ b/docs/api/spec/treetracker-token-api.yaml @@ -230,10 +230,9 @@ paths: get: tags: - Managed wallets - summary: Get all wallets managed by the logged in account. This endpoint is also used to get the total number of tokens in a given wallet. Each wallet also returns all trust relationships for that wallet that have not been deleted + summary: 'Get all wallets managed by the logged in account. This endpoint is also used to get the total number of tokens in a given wallet. Each wallet also returns all trust relationships for that wallet that have not been deleted.' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - - $ref: '#/components/parameters/contentTypeJsonHeader' - name: limit in: query description: Number of items to return @@ -257,66 +256,104 @@ paths: example: 10 - name: order_by in: query - description: 'column to order by, only created_at currently supported' + description: 'Column to order by, only `created_at` is currently supported' required: false style: form explode: true schema: - type: timestamp + type: string + default: 'created_at' + example: 'created_at' - name: order in: query - description: 'either asc or desc' + description: 'Either `asc` or `desc`' required: false style: form explode: true schema: type: string + default: 'desc' + example: 'asc' - name: created_at_start_date in: query - description: 'date to start checking from' + description: 'Date to start checking from, ISO date format' required: false style: form explode: true schema: - type: timestamp + type: string + format: date-time + example: '2021-08-09%2020:56:56.999999' - name: created_at_end_date in: query - description: 'date to stop checking at' + description: 'Date to stop checking at, ISO format' required: false style: form explode: true schema: - type: timestamp + type: string + format: date-time + example: '2021-08-19%2020:56:56.999999' responses: '200': - description: '' + description: 'Returns list of managed wallets' content: application/json: schema: $ref: '#/components/schemas/walletsResponse' + '401': + $ref: '#/components/responses/UnauthorizedError' + '403': + $ref: '#/components/responses/ForbiddenError' + '422': + description: 'Missing or invalid query parameters' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"limit" is required' deprecated: false post: tags: - Managed wallets - summary: Create a new managed wallet - description: Create a new managed wallet. Requires the manage_account role. + summary: 'Create a new managed wallet' + description: 'Create a new managed wallet. Requires the manage_account role.' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - $ref: '#/components/parameters/contentTypeJsonHeader' requestBody: - description: '' + description: 'Wallet creation request' content: application/json: schema: - $ref: '#/components/schemas/accountrequest' + $ref: '#/components/schemas/accountRequest' example: wallet: sprinter_van_2004 required: true responses: - '201': - description: A new wallet was created + '200': + description: 'A new wallet was created' + content: + application/json: + schema: + $ref: '#/components/schemas/accountRequest' '401': $ref: '#/components/responses/UnauthorizedError' + '403': + $ref: '#/components/responses/ForbiddenError' + '415': + $ref: '#/components/responses/UnsupportedMediaTypeError' + '422': + description: 'Missing or invalid parameters in request body' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"wallet" is not allowed to be empty' deprecated: false /transfers: post: @@ -927,8 +964,8 @@ components: capture: type: string example: '/webmap/tree?uuid=8df635f6-2df8-496f-93da-3060fc1e3180' - accountrequest: - title: accountrequest + accountRequest: + title: accountRequest required: - wallet type: object @@ -947,14 +984,23 @@ components: walletItem: title: Wallet Details properties: - wallet: + id: type: string - email: + format: uuid + example: 'ef6a37ce-c459-4a2c-83c3-85e829e4a75e' + logo_url: type: string - phone: + format: url + example: https://www.placehold.co/192x192 + about: + type: string + example: 'feugiat pretium nibh ipsum consequat nisl vel pretium lectus quam id leo in vitae turpis massa sed elementum tempus egestas' + wallet: type: string + example: testwallet tokens_in_wallet: type: integer + example: 12 transferrequest: title: transferrequest required: From d0f5897facc5ba0097ee31ab711e793cddf00d35 Mon Sep 17 00:00:00 2001 From: Pranav Kakaraparti Date: Thu, 31 Aug 2023 04:01:49 -0500 Subject: [PATCH 06/12] feat: /wallets/:id/trust_relationships --- docs/api/spec/treetracker-token-api.yaml | 113 +++++++++++++++++++++-- 1 file changed, 103 insertions(+), 10 deletions(-) diff --git a/docs/api/spec/treetracker-token-api.yaml b/docs/api/spec/treetracker-token-api.yaml index 6fa4a08a..89bbf6b1 100644 --- a/docs/api/spec/treetracker-token-api.yaml +++ b/docs/api/spec/treetracker-token-api.yaml @@ -355,6 +355,42 @@ paths: code: 422 message: '"wallet" is not allowed to be empty' deprecated: false + '/wallets/{wallet_uuid}/trust_relationships': + get: + tags: + - Managed wallets + summary: Get list of trust relationships for the specified wallet + parameters: + - $ref: '#/components/parameters/treetrackerApiKeyParam' + - name: wallet_uuid + description: 'ID of wallet' + in: path + required: true + schema: + type: string + format: uuid + example: 496ffa8e-2fa2-488c-98e1-acf9b57c230b + responses: + '200': + description: 'Return list of trust relationships for the wallet matching wallet_uuid' + content: + application/json: + schema: + $ref: '#/components/schemas/trustRelationshipsResponse' + '401': + $ref: '#/components/responses/UnauthorizedError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + description: 'No wallet found matching wallet_uuid' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 404 + message: 'Could not find wallet by id: ef6a37ce-c459-4a2c-83c3-85e829e4a753' + deprecated: false /transfers: post: tags: @@ -1257,7 +1293,7 @@ components: created_at: type: string trustRelationshipsResponse: - title: Trust Relationship Responses + title: Trust Relationships Response type: object properties: trust_relationships: @@ -1269,21 +1305,32 @@ components: type: object properties: id: - type: integer - actor_wallet: - type: string - target_wallet: - type: string - trust_type: type: string + format: uuid + example: 0b335cd4-db82-4784-89f5-c8800844c291 + type: + $ref: '#/components/schemas/trustType' + request_type: + $ref: '#/components/schemas/trustRequestType' state: + $ref: '#/components/schemas/trustStateType' + created_at: type: string - trust_request_type: + format: date-time + example: 2023-08-15T23:29:12.261Z + updated_at: type: string - orginating_wallet: + format: date-time + example: 2023-08-15T23:29:12.261Z + originating_wallet: type: string - created_at: + example: testuser + actor_wallet: + type: string + example: testuser + target_wallet: type: string + example: otherwallet walletNameOrId: oneOf: - type: string @@ -1298,6 +1345,52 @@ components: type: integer message: type: string + trustStateType: + type: string + enum: + - requested + - cancelled_by_originator + - cancelled_by_actor + - cancelled_by_target + - trusted + example: trusted + description: > + Trust state type: + * `requested` - The trust relationship is pending approval. + * `cancelled_by_originator` - The trust relationship was cancelled by the originator. + * `cancelled_by_actor` - The trust relationship was cancelled by the actor. + * `cancelled_by_target` - The trust relationship was cancelled by the target. + * `trusted` - The trust relationship is active. + trustRequestType: + type: string + enum: + - send + - receive + - manage + - yield + - deduct + - release + example: manage + description: > + Trust Request type: + * `send` - Request to allow actor to send to target. + * `receive` - Request a send privilege to a wallet controlled by the originator on behalf of another sending wallet (opposite direction of send trust request). + * `manage` - Request to allow actor to move funds from target wallet to any other wallet they control. + * `yield` - Request to give manage privilege on a wallet controlled by the originator to another wallet (opposite direction of manage trust request). + * `deduct` - Request to allow actor to deduct from wallet. + * `release` - Request a deduct privilege from a wallet controlled by the originator on behalf of another deducting wallet (opposite direction of deduct trust request). + trustType: + type: string + enum: + - send + - deduct + - manage + example: send + description: > + Trust Type: + * `send` - Allow actor to send to target. + * `deduct` - Allow actor to deduct from wallet. + * `manage` - Allow actor to move funds from target wallet to any other wallet they control. responses: UnauthorizedError: description: Access bearer token is missing or invalid From e678ce9c0e193fff5bfa226af7c4aac2e0a7da3b Mon Sep 17 00:00:00 2001 From: Pranav Kakaraparti Date: Thu, 31 Aug 2023 05:39:39 -0500 Subject: [PATCH 07/12] feat: /wallets/batch-create-wallet --- docs/api/spec/treetracker-token-api.yaml | 117 ++++++++++++++++++++++- 1 file changed, 115 insertions(+), 2 deletions(-) diff --git a/docs/api/spec/treetracker-token-api.yaml b/docs/api/spec/treetracker-token-api.yaml index 89bbf6b1..24dec035 100644 --- a/docs/api/spec/treetracker-token-api.yaml +++ b/docs/api/spec/treetracker-token-api.yaml @@ -391,6 +391,47 @@ paths: code: 404 message: 'Could not find wallet by id: ef6a37ce-c459-4a2c-83c3-85e829e4a753' deprecated: false + /wallets/batch-create-wallet: + post: + tags: + - Managed wallets + summary: 'Batch Create Wallets' + description: 'Create multiple wallets using a CSV file.' + parameters: + - $ref: '#/components/parameters/treetrackerApiKeyParam' + - $ref: '#/components/parameters/contentTypeMultipartHeader' + requestBody: + description: 'Wallet batch create request' + content: + multipart/form-data: + schema: + $ref: '#/components/schemas/batchCreateRequest' + encoding: + csv: + contentType: text/csv + required: true + responses: + '200': + description: 'Batch create response' + content: + application/json: + schema: + $ref: '#/components/schemas/batchCreateResponse' + '401': + $ref: '#/components/responses/UnauthorizedError' + '403': + $ref: '#/components/responses/ForbiddenError' + '415': + $ref: '#/components/responses/MultipartMediaTypeError' + '422': + description: 'Missing or invalid parameters in request body' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"sender_wallet" is not allowed to be empty' /transfers: post: tags: @@ -892,6 +933,15 @@ components: schema: type: string example: application/json + contentTypeMultipartHeader: + name: Content-Type + in: header + description: '' + required: true + style: simple + schema: + type: string + example: multipart/form-data schemas: authRequest: title: Authentication Request @@ -1391,11 +1441,65 @@ components: * `send` - Allow actor to send to target. * `deduct` - Allow actor to deduct from wallet. * `manage` - Allow actor to move funds from target wallet to any other wallet they control. + batchCreateRequest: + title: 'Batch create request' + required: + - csv + type: object + properties: + sender_wallet: + type: string + example: wallet1 + token_transfer_amount_default: + type: integer + example: 5 + csv: + type: string + format: binary + description: 'Must be a `.csv` file' + batchCreateResponse: + title: 'Batch create response' + type: object + properties: + wallets_created: + type: integer + wallets_already_exists: + type: array + items: + type: string + wallet_other_failure_count: + type: integer + extra_wallet_information_saved: + type: integer + extraWalletInformationNotSaved: + type: array + items: + type: string + example: + wallets_created: 3 + wallets_already_exists: [ ] + wallet_other_failure_count: 0 + extra_wallet_information_saved: 0 + extraWalletInformationNotSaved: [ ] responses: UnauthorizedError: - description: Access bearer token is missing or invalid + description: 'API key is missing or invalid, or some permission is missing.' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 401 + message: 'Invalid access - no API key' ForbiddenError: - description: Access denied for that resource + description: 'Access bearer token is missing or invalid, or some permission is missing, etc.' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 403 + message: 'ERROR: Authentication, no token supplied for protected path' UnsupportedMediaTypeError: description: Invalid content type content: @@ -1405,6 +1509,15 @@ components: example: code: 415 message: 'Invalid content type. API only supports application/json' + MultipartMediaTypeError: + description: Invalid content type + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 415 + message: 'Invalid content type. API only supports multipart/form-data' securitySchemes: httpBearer: type: http From 1cdb41774ea1c348b3a75f047d529e2b27e6f168 Mon Sep 17 00:00:00 2001 From: Pranav Kakaraparti Date: Thu, 31 Aug 2023 05:57:40 -0500 Subject: [PATCH 08/12] feat: /wallets/batch-transfer --- docs/api/spec/treetracker-token-api.yaml | 62 ++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/docs/api/spec/treetracker-token-api.yaml b/docs/api/spec/treetracker-token-api.yaml index 24dec035..c4cc33a9 100644 --- a/docs/api/spec/treetracker-token-api.yaml +++ b/docs/api/spec/treetracker-token-api.yaml @@ -432,6 +432,51 @@ paths: example: code: 422 message: '"sender_wallet" is not allowed to be empty' + deprecated: false + /wallets/batch-transfer: + post: + tags: + - Managed wallets + summary: 'Batch transfer' + description: 'Create multiple transfers using a CSV file.' + parameters: + - $ref: '#/components/parameters/treetrackerApiKeyParam' + - $ref: '#/components/parameters/contentTypeMultipartHeader' + requestBody: + content: + multipart/form-data: + schema: + $ref: '#/components/schemas/batchTransferRequest' + encoding: + csv: + contentType: text/csv + responses: + '200': + description: 'Successful batch transfer response' + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: 'batch transfer successfull' + '401': + $ref: '#/components/responses/UnauthorizedError' + '403': + $ref: '#/components/responses/ForbiddenError' + '415': + $ref: '#/components/responses/MultipartMediaTypeError' + '422': + description: 'Missing or invalid parameters in request body' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"sender_wallet" is required' + deprecated: false /transfers: post: tags: @@ -1481,6 +1526,23 @@ components: wallet_other_failure_count: 0 extra_wallet_information_saved: 0 extraWalletInformationNotSaved: [ ] + batchTransferRequest: + title: 'Batch transfer request' + required: + - csv + - sender_wallet + type: object + properties: + sender_wallet: + type: string + example: wallet1 + token_transfer_amount_default: + type: integer + example: 5 + csv: + type: string + format: binary + description: 'Must be a `.csv` file' responses: UnauthorizedError: description: 'API key is missing or invalid, or some permission is missing.' From 5e3e7eea88cf8f836f286ee7074e3baadeb2e185 Mon Sep 17 00:00:00 2001 From: Pranav Kakaraparti Date: Thu, 31 Aug 2023 14:13:59 -0500 Subject: [PATCH 09/12] feat: /transfers --- docs/api/spec/treetracker-token-api.yaml | 291 +++++++++++++++-------- 1 file changed, 192 insertions(+), 99 deletions(-) diff --git a/docs/api/spec/treetracker-token-api.yaml b/docs/api/spec/treetracker-token-api.yaml index c4cc33a9..d85b342c 100644 --- a/docs/api/spec/treetracker-token-api.yaml +++ b/docs/api/spec/treetracker-token-api.yaml @@ -487,26 +487,11 @@ paths: - $ref: '#/components/parameters/treetrackerApiKeyParam' - $ref: '#/components/parameters/contentTypeJsonHeader' requestBody: - description: '' + description: 'Request body for creating a transfer' content: application/json: schema: - $ref: '#/components/schemas/transferrequest' - examples: - ExplicitTokens: - value: - tokens: - - e1b278e8-f025-44b7-9dd8-36ffb2d58f7e - - e533653e-2dbf-48cd-940a-a87e5a393158 - sender_wallet: zaven4 - receiver_wallet: 2 - Bundle: - value: - bundle: - bundle_size: 100 - matching_all_tags: - - pine - - Tanzania + $ref: '#/components/schemas/transferRequest' required: true responses: '201': @@ -514,15 +499,33 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/sendRequestProcessedResponse' + $ref: '#/components/schemas/transferItem' '202': - description: 'The transfer could not be completely processed because a trust relationship does not exist allowing for automated processing. If a the source wallet is controlled by the authenitcated user, a transfer in the pending state has been created. If the source wallet is not controlled but the authenticated user, but the destination wallet is, then a transfer in the requested state has been created' + $ref: '#/components/responses/transferPendingResponse' + '401': + $ref: '#/components/responses/UnauthorizedError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + description: 'No wallet found matching input ID' content: application/json: schema: - $ref: '#/components/schemas/sendRequestPendingResponse' - '401': - $ref: '#/components/responses/UnauthorizedError' + $ref: '#/components/schemas/errorResponse' + example: + code: 404 + message: 'Could not find wallet by name: bad_wallet' + '415': + $ref: '#/components/responses/UnsupportedMediaTypeError' + '422': + description: 'Missing or invalid parameters in request body' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"receiver_wallet" is not allowed to be empty' get: tags: - Transfers @@ -530,19 +533,16 @@ paths: description: 'Get requested, pending, completed, cancelled and failed transfers for wallets (by name or id). The authenticated wallet is either the source, destination, or originating wallet entity.' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - - $ref: '#/components/parameters/contentTypeJsonHeader' - in: query name: state schema: - type: string + $ref: '#/components/schemas/transferState' required: false description: 'requested, pending, completed, cancelled, failed' - in: query name: wallet schema: - oneOf: - - type: string - - type: number + $ref: '#/components/schemas/walletNameOrId' required: false description: 'filter transfers matches the source, destination, or originating wallet (by name or id) of a transfer' - name: limit @@ -569,8 +569,28 @@ paths: responses: '200': description: Return array of matching transfers + content: + application/json: + schema: + type: object + properties: + transfers: + type: array + items: + $ref: '#/components/schemas/transferItem' '401': $ref: '#/components/responses/UnauthorizedError' + '403': + $ref: '#/components/responses/ForbiddenError' + '422': + description: 'Missing or invalid parameters in request body' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"limit" is required' '/transfers/{transfer_id}': get: tags: @@ -1132,44 +1152,63 @@ components: tokens_in_wallet: type: integer example: 12 - transferrequest: - title: transferrequest - required: - - tokens - - sender_wallet - - receiver_wallet - type: object - properties: - tokens: - type: array - items: - type: string - description: '' - bundle: - type: object - properties: - bundle_size: - type: integer - description: required number of trees to transfer - matching_all_tags: + transferRequest: + title: Transfer Request + oneOf: + - properties: + tokens: type: array items: type: string - description: optional list of tags that trees must match ALL of - sender_wallet: - oneOf: - - type: string - - type: number - receiver_wallet: - oneOf: - - type: string - - type: number - example: - tokens: - - e1b278e8-f025-44b7-9dd8-36ffb2d58f7e - - e533653e-2dbf-48cd-940a-a87e5a393158 - sender_wallet: zaven4 - receiver_wallet: zaven + format: uuid + description: 'Explicitly transfer tokens' + sender_wallet: + oneOf: + - type: string + - type: string + format: uuid + receiver_wallet: + oneOf: + - type: string + - type: string + format: uuid + required: + - tokens + - sender_wallet + - receiver_wallet + example: + tokens: + - e1b278e8-f025-44b7-9dd8-36ffb2d58f7e + - e533653e-2dbf-48cd-940a-a87e5a393158 + sender_wallet: wallet1 + receiver_wallet: wallet2 + - properties: + bundle: + type: object + description: 'Transfer some amount of token' + properties: + bundle_size: + type: integer + description: required number of trees to transfer + sender_wallet: + oneOf: + - type: string + - type: string + format: uuid + receiver_wallet: + oneOf: + - type: string + - type: string + format: uuid + required: + - bundle + - sender_wallet + - receiver_wallet + example: + bundle: + bundle_size: 100 + sender_wallet: wallet1 + receiver_wallet: wallet2 transferbundlerequest: title: transferbundlerequest required: @@ -1192,6 +1231,68 @@ components: bundle_size: 500 sender_wallet: zaven receiver_wallet: GreenEarthAppeal + transferItem: + title: Transfer Details + properties: + id: + type: string + format: uuid + description: 'The unique ID for this transfer' + example: cf0ce129-8c12-45cf-b914-a8f1cb6b7dc5 + type: + $ref: '#/components/schemas/transferType' + parameters: + type: object + oneOf: + - properties: + bundle: + type: object + properties: + bundleSize: + type: integer + description: Number of tokens associated with the transfer + example: 2 + required: + - bundleSize + - properties: + tokens: + type: array + items: + type: string + description: Array of explicit tokens + state: + $ref: '#/components/schemas/transferState' + created_at: + type: string + format: date-time + example: 2023-08-02T21:46:35.134Z + closed_at: + type: string + format: date-time + example: 2023-08-02T21:46:35.134Z + active: + type: boolean + example: true + claim: + type: boolean + example: false + originating_wallet: + type: string + example: testuser + source_wallet: + type: string + example: testuser + destination_wallet: + type: string + example: wallet22 + transferType: + type: string + enum: + - send + - deduct + - managed + example: send + description: 'The type of transfer. The value is computed by the server based on the submitted request' sendrequest: title: sendrequest required: @@ -1213,43 +1314,6 @@ components: - e1b278e8-f025-44b7-9dd8-36ffb2d58f7e - e533653e-2dbf-48cd-940a-a87e5a393158 receiver_wallet: zaven - sendRequestProcessedResponse: - title: sendRequestProcessedResponse - type: object - properties: - id: - type: string - description: The unique ID for this transfer - originating_wallet: - type: string - source_wallet: - type: string - destination_wallet: - type: string - type: - type: string - description: 'the type of transfer. send, deduct, or managed. the value is computed by the server based on the submitted request' - parameters: - $ref: '#/components/schemas/requestBundleRequestParameters' - state: - type: string - description: 'the state of the transfer. requested, pending, completed, cancelled, or failed' - created_at: - type: string - closed_at: - type: string - example: - originating_wallet: johnwallet1 - source_wallet: planeter - destination_wallet: just.a.guy - type: send - parameters: - $ref: '#/components/schemas/requestBundleRequestParameters' - state: completed - created_at: '2020-07-09T00:41:49+00:00' - closed_at: '2020-07-09T00:41:49+00:00' - sendRequestPendingResponse: - title: sendRequestPendingResponse sendBundleRequest: title: sendBundleRequest type: object @@ -1486,6 +1550,15 @@ components: * `send` - Allow actor to send to target. * `deduct` - Allow actor to deduct from wallet. * `manage` - Allow actor to move funds from target wallet to any other wallet they control. + transferState: + type: string + enum: + - requested + - pending + - completed + - cancelled + - failed + example: pending batchCreateRequest: title: 'Batch create request' required: @@ -1580,6 +1653,26 @@ components: example: code: 415 message: 'Invalid content type. API only supports multipart/form-data' + transferPendingResponse: + description: 'The transfer could not be completely processed because a trust relationship does not exist allowing for automated processing. If a the source wallet is controlled by the authenticated user, a transfer in the pending state has been created. If the source wallet is not controlled but the authenticated user, but the destination wallet is, then a transfer in the requested state has been created' + content: + application/json: + schema: + $ref: '#/components/schemas/transferItem' + example: + id: 251debc2-9077-4876-b710-f5543c9a7719 + type: send + parameters: + bundle: + bundleSize: 1 + state: pending + created_at: '2023-08-31T05:02:52.623Z' + closed_at: '2023-08-31T05:02:52.623Z' + active: true + claim: false + originating_wallet: testuser + source_wallet: wallet1 + destination_wallet: wallet2 securitySchemes: httpBearer: type: http From 893b74bc254d7f68f8f5ac9748ccbd499a37389d Mon Sep 17 00:00:00 2001 From: Pranav Kakaraparti Date: Thu, 31 Aug 2023 15:14:22 -0500 Subject: [PATCH 10/12] feat: /transfers/:id/* --- docs/api/spec/treetracker-token-api.yaml | 371 +++++++++++++++-------- 1 file changed, 249 insertions(+), 122 deletions(-) diff --git a/docs/api/spec/treetracker-token-api.yaml b/docs/api/spec/treetracker-token-api.yaml index d85b342c..c3690281 100644 --- a/docs/api/spec/treetracker-token-api.yaml +++ b/docs/api/spec/treetracker-token-api.yaml @@ -595,202 +595,284 @@ paths: get: tags: - Transfers - summary: Get information of a single transfer + summary: 'Get information of a single transfer' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - - $ref: '#/components/parameters/contentTypeJsonHeader' - name: transfer_id in: path - description: '' + description: 'The unique ID for the transfer' required: true schema: - type: integer - format: int32 + type: string + format: uuid + example: 03537683-5356-42f4-97b2-95ba287a453f responses: '200': - description: '' + description: 'Return the transfer matching the transfer_id' + content: + application/json: + schema: + $ref: '#/components/schemas/transferItem' '401': $ref: '#/components/responses/UnauthorizedError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + description: 'No transfer found matching input ID' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 404 + message: 'Transfer does not exist, or it is not related to this wallet' + '422': + description: 'Invalid query parameters' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"transfer_id" must be a valid GUID' delete: tags: - Transfers - summary: Cancel a pending or requested transfer that has not closed - description: Cancel a pending (untrusted) or requested transfer. The executor can delete the pending/requested transfer before it is executed. Transfer is marked canceled by this command. + summary: 'Cancel a pending or requested transfer that has not closed' + description: 'Cancel a pending (untrusted) or requested transfer. The executor can delete the pending/requested transfer before it is executed. Transfer is marked canceled by this command.' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - - $ref: '#/components/parameters/contentTypeJsonHeader' - name: transfer_id in: path - description: '' + description: 'The unique ID for the transfer' required: true schema: - type: integer - format: int32 + type: string + format: uuid + example: 03537683-5356-42f4-97b2-95ba287a453f responses: '200': - description: Transfer was marked canceled + $ref: '#/components/responses/transferCancelledResponse' '401': $ref: '#/components/responses/UnauthorizedError' '403': - description: Authenticated wallet does not have access to this transfer + $ref: '#/components/responses/ForbiddenError' '404': - description: No transfer record with that id + description: 'No transfer found matching the transfer_id or the transfer is not associated with the logged in wallet' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 404 + message: 'Cannot find transfer by id:03537683-5356-42f4-97b2-95ba287a453b' '406': description: Transfer with this id is not in requested or pending state - '/transfers/{transfer_id}/accept': - post: + '/transfers/{transfer_id}/tokens': + get: tags: - Transfers - summary: Accept a pending (untrusted) transfer + summary: 'Get all tokens linked to a single transfer' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - - $ref: '#/components/parameters/contentTypeJsonHeader' - name: transfer_id in: path - description: '' + description: 'The unique ID for the transfer' required: true + schema: + type: string + format: uuid + example: 03537683-5356-42f4-97b2-95ba287a453f + - name: limit + in: query + description: Number of items to return + required: true + style: form + explode: true + schema: + type: integer + format: int32 + example: 10 + - name: start + in: query + description: 'Where does the list start, 1 means start from the beginning of the list' + required: false + style: form + explode: true schema: type: integer format: int32 + default: 1 + example: 10 responses: '200': - description: '' + description: 'Returns list of tokens associated with the transfer' + content: + application/json: + schema: + type: object + properties: + tokens: + type: array + items: + $ref: '#/components/schemas/tokenItemWithLinks' '401': $ref: '#/components/responses/UnauthorizedError' - '/transfers/{transfer_id}/decline': + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + description: 'No transfer found matching the transfer_id or the transfer is not associated with the logged in wallet' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 404 + message: 'Transfer does not exist, or it is not related to this wallet' + '422': + description: 'Invalid query parameters' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"transfer_id" must be a valid GUID' + '/transfers/{transfer_id}/accept': post: tags: - Transfers - summary: Decline a pending (untrusted) transfer + summary: 'Accept a pending (untrusted) transfer' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - $ref: '#/components/parameters/contentTypeJsonHeader' - name: transfer_id in: path - description: '' + description: 'The unique ID for the transfer' required: true schema: - type: integer - format: int32 + type: string + format: uuid + example: 03537683-5356-42f4-97b2-95ba287a453f responses: '200': - description: '' + $ref: '#/components/responses/transferAcceptedResponse' '401': $ref: '#/components/responses/UnauthorizedError' - '/transfers/{transfer_id}/fulfill': - parameters: - - $ref: '#/components/parameters/treetrackerApiKeyParam' - - $ref: '#/components/parameters/contentTypeJsonHeader' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + description: 'No transfer found matching the transfer_id or the transfer is not associated with the logged in wallet' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 404 + message: 'Cannot find transfer by id:df80b648-4fef-4ca6-b704-9e7e1c77d1ef' + '415': + $ref: '#/components/responses/UnsupportedMediaTypeError' + '422': + description: 'Invalid query parameters' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"transfer_id" must be a valid GUID' + '/transfers/{transfer_id}/decline': post: tags: - Transfers - summary: Fullfill a requested transfer - description: Post a list of tokens to fulfill the parameters of a transfer request that specifies tokens using a bundle. This allows the debited wallet to decide which tokens matching the bundle parameters to attach to the transfer. Application logic must check that each token matches the parameters of the request. + summary: 'Decline a pending (untrusted) transfer' parameters: + - $ref: '#/components/parameters/treetrackerApiKeyParam' + - $ref: '#/components/parameters/contentTypeJsonHeader' - name: transfer_id in: path - description: the id of the transfer record on the server + description: 'The unique ID for the transfer' required: true - style: simple schema: - type: integer - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/requestBundleFulfillBody' + type: string + format: uuid + example: 03537683-5356-42f4-97b2-95ba287a453f responses: '200': - description: '' + $ref: '#/components/responses/transferCancelledResponse' '401': $ref: '#/components/responses/UnauthorizedError' - '/transfers/{transfer_id}/tokens': - get: + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + description: 'No transfer found matching the transfer_id or the transfer is not associated with the logged in wallet' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 404 + message: 'Cannot find transfer by id:df80b648-4fef-4ca6-b704-9e7e1c77d1ef' + '415': + $ref: '#/components/responses/UnsupportedMediaTypeError' + '422': + description: 'Invalid query parameters' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"transfer_id" must be a valid GUID' + '/transfers/{transfer_id}/fulfill': + post: tags: - Transfers - summary: Get all tokens linked to a single transfer + summary: 'Fulfill a requested transfer' + description: 'Post a list of tokens to fulfill the parameters of a transfer request that specifies tokens using a bundle. This allows the debited wallet to decide which tokens matching the bundle parameters to attach to the transfer. Application logic must check that each token matches the parameters of the request.' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - $ref: '#/components/parameters/contentTypeJsonHeader' - name: transfer_id in: path - description: '' + description: 'The unique ID for the transfer' required: true schema: - type: integer - format: int32 - - name: limit - in: query - description: Number of items to return - required: true - style: form - explode: true - schema: - type: integer - format: int32 - example: 10 - - name: start - in: query - description: 'Where does the list start, 1 means start from the beginning of the list' - required: false - style: form - explode: true - schema: - type: integer - format: int32 - default: 1 - example: 10 + type: string + format: uuid + example: 03537683-5356-42f4-97b2-95ba287a453f + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/requestBundleFulfillBody' responses: '200': - description: '' + $ref: '#/components/responses/transferAcceptedResponse' '401': $ref: '#/components/responses/UnauthorizedError' - /events: - get: - tags: - - Event stream - summary: Get event stream for wallet - description: 'The event stream contains notifications about execute and pending transfers, transfer request, trust requests, trust deletions, and trust approvals. Event streams for managed wallets can also be requested' - parameters: - - $ref: '#/components/parameters/treetrackerApiKeyParam' - - $ref: '#/components/parameters/contentTypeJsonHeader' - - name: limit - in: query - description: The number of records to return - required: true - style: form - explode: true - schema: - type: integer - format: int32 - example: 10 - - name: since - in: query - description: Only return events since a given timestamp - required: true - style: form - explode: true - schema: - type: string - format: timestamp - example: '2019-10-12T07:20:50.52Z' - - name: wallet - description: Wallet (by name or id) can be specified if the authenticated wallet manages other wallets. The default is to return events matching the authenticated wallet - in: query - schema: - oneOf: - - type: string - - type: number - example: zaven2 - responses: - '200': - description: '' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + description: 'No transfer found matching the transfer_id or the transfer is not associated with the logged in wallet' content: application/json: schema: - $ref: '#/components/schemas/eventStream' - '401': - $ref: '#/components/responses/UnauthorizedError' + $ref: '#/components/schemas/errorResponse' + example: + code: 404 + message: 'Cannot find transfer by id:df80b648-4fef-4ca6-b704-9e7e1c77d1ef' + '415': + $ref: '#/components/responses/UnsupportedMediaTypeError' + '422': + description: 'Invalid query parameters' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"transfer_id" must be a valid GUID' /trust_relationships: get: tags: @@ -1381,15 +1463,20 @@ components: requestBundleFulfillBody: title: Transfer Request Fulfillment type: object - properties: - tokens: - type: array - items: - type: string - description: optional array of explicit tokens - implicit: - type: boolean - description: automatically fill the request with tokens matching the specified parameters if set + oneOf: + - properties: + tokens: + type: array + items: + type: string + format: uuid + description: 'Array of explicit tokens' + example: [ 'ed155d71-67f0-4d21-a73d-f5445b8c43c8' ] + - properties: + implicit: + type: boolean + description: 'Automatically fill the request with tokens matching the specified parameters if set' + example: true trustRequest: title: Trust Request type: object @@ -1673,6 +1760,46 @@ components: originating_wallet: testuser source_wallet: wallet1 destination_wallet: wallet2 + transferCancelledResponse: + description: 'Transfer is marked as cancelled' + content: + application/json: + schema: + $ref: '#/components/schemas/transferItem' + example: + id: df80b648-4fef-4ca6-b704-9e7e1c77d1ed + type: send + parameters: + bundle: + bundleSize: '1' + state: cancelled + created_at: '2023-08-01T22:09:35.642Z' + closed_at: '2023-08-01T22:09:35.642Z' + active: true + claim: false + originating_wallet: testuser + source_wallet: testuser + destination_wallet: wallet2 + transferAcceptedResponse: + description: 'Transfer is marked as completed' + content: + application/json: + schema: + $ref: '#/components/schemas/transferItem' + example: + id: df80b648-4fef-4ca6-b704-9e7e1c77d1ed + type: send + parameters: + bundle: + bundleSize: '1' + state: completed + created_at: '2023-08-01T22:09:35.642Z' + closed_at: '2023-08-01T22:09:35.642Z' + active: true + claim: false + originating_wallet: testuser + source_wallet: testuser + destination_wallet: wallet2 securitySchemes: httpBearer: type: http From d0cfde7ec735cfa049100d66d5c6a06ddf712257 Mon Sep 17 00:00:00 2001 From: Pranav Kakaraparti Date: Thu, 31 Aug 2023 16:14:12 -0500 Subject: [PATCH 11/12] feat: /trust_relationships/* --- docs/api/spec/treetracker-token-api.yaml | 218 +++++++++++++++-------- 1 file changed, 144 insertions(+), 74 deletions(-) diff --git a/docs/api/spec/treetracker-token-api.yaml b/docs/api/spec/treetracker-token-api.yaml index c3690281..e57b0dbc 100644 --- a/docs/api/spec/treetracker-token-api.yaml +++ b/docs/api/spec/treetracker-token-api.yaml @@ -880,11 +880,10 @@ paths: summary: 'Get a list of existing, requested, and pending trust relationships' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - - $ref: '#/components/parameters/contentTypeJsonHeader' - name: limit in: query description: Number of items to return - required: true + required: false style: form explode: true schema: @@ -904,83 +903,49 @@ paths: example: 10 - name: state in: query - description: Filter by state of the trust relationship + description: 'Filter by state of the trust relationship' required: false style: form schema: - type: string - examples: - Trusted: - value: trusted - description: Active trust relationship - Requested: - value: requested - description: Trust relationship pending approval - CancelledByOriginator: - value: cancelled_by_originator - description: Trust relationship was cancelled by the originator - CancelledByActor: - value: cancelled_by_actor - description: Trust relationship was cancelled by the actor - CancelledByTarget: - value: cancelled_by_target - description: Trust relationship was cancelled by the target + $ref: '#/components/schemas/trustStateType' - name: type in: query - description: Type of trust relationship + description: 'Type of the trust relationship' required: false style: form schema: - type: string - examples: - Send: - value: send - description: Allow actor to send to target - Deduct: - value: deduct - description: Allow actor to deduct from wallet - Manage: - value: manage - description: Allow actor to move funds from target wallet to any other wallet they control + $ref: '#/components/schemas/trustType' - name: request_type in: query - description: Type of trust relationship + description: 'Type of the trust relationship request' required: false style: form schema: - type: string - examples: - Send: - value: send - description: Request to allow actor to send to target - Receive: - value: receive - description: Request a send priviledge to a wallet controlled by the originator on behalf of another sending wallet (opposite direction of send trust request) - Deduct: - value: deduct - description: Request to allow actor to deduct from wallet - Release: - value: release - description: Request a deduct priviledge from a wallet controlled by the originator on behalf of another deducting wallet (opposite direction of deduct trust request) - Manage: - value: manage - description: Request to allow actor to move funds from target wallet to any other wallet they control - Yield: - value: manage - description: Request to give manage privilege on a wallet controlled by the originator to another wallet (opposite direction of manage trust request) + $ref: '#/components/schemas/trustRequestType' responses: '200': - description: '' + description: 'Returns list of trust relationships' content: application/json: schema: $ref: '#/components/schemas/trustRelationshipsResponse' '401': $ref: '#/components/responses/UnauthorizedError' + '403': + $ref: '#/components/responses/ForbiddenError' + '422': + description: 'Invalid query parameters' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"limit" must be a number' post: tags: - Trust relationships - summary: Request a new trust relationship from another wallet + summary: 'Request a new trust relationship from another wallet' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - $ref: '#/components/parameters/contentTypeJsonHeader' @@ -990,77 +955,152 @@ paths: schema: $ref: '#/components/schemas/trustRequest' responses: - '202': - description: Accepted but waiting for approval + '200': + $ref: '#/components/responses/trustRelationshipRequestedResponse' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' + '404': + description: 'No wallet found matching the input wallet name' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 404 + message: 'Could not find wallet by name: bad_wallet' + '415': + $ref: '#/components/responses/UnsupportedMediaTypeError' + '422': + description: 'Invalid or missing parameters in request body' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 422 + message: '"trust_request_type" is required' '/trust_relationships/{trust_relationship_id}': delete: tags: - Trust relationships - summary: Remove a trust relationship linked to the autheticated wallet - description: Remove a trust relationship linked to the autheticated wallet. This could be either the actor wallet or the target wallet + summary: 'Remove a trust relationship linked to the authenticated wallet' + description: 'Remove a trust relationship linked to the authenticated wallet. This could be either the actor wallet or the target wallet.' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - - $ref: '#/components/parameters/contentTypeJsonHeader' - name: trust_relationship_id in: path - description: the id of the entity trust record on the server + description: 'The ID of the entity trust record on the server' required: true style: simple schema: - type: integer + type: string + format: uuid + example: 03537683-5356-42f4-97b2-95ba287a453f responses: '200': - description: '' + description: 'Trust relationship state is changed to `cancelled_by_originator`' + content: + application/json: + schema: + $ref: '#/components/schemas/trustRelationshipItem' + example: + id: c04e3b02-971c-4268-a701-b6c01468ca62 + type: send + request_type: send + state: cancelled_by_originator + created_at: '2023-08-19T03:40:38.200Z' + updated_at: '2023-08-19T03:40:38.200Z' + originating_wallet: testuser + actor_wallet: testuser + target_wallet: testWallet11 '401': $ref: '#/components/responses/UnauthorizedError' + '403': + $ref: '#/components/responses/ForbiddenError' + '404': + $ref: '#/components/responses/trustRelationshipNotFound' '/trust_relationships/{trust_relationship_id}/accept': post: tags: - Trust relationships - summary: Accept a trust relationship + summary: 'Accept a trust relationship' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - $ref: '#/components/parameters/contentTypeJsonHeader' - name: trust_relationship_id in: path - description: the id of the entity trust record on the server + description: 'The ID of the entity trust record on the server' required: true style: simple schema: - type: integer + type: string + format: uuid + example: 03537683-5356-42f4-97b2-95ba287a453f responses: '200': - description: '' + description: 'Trust relationship state is changed to `trusted`' + content: + application/json: + schema: + $ref: '#/components/schemas/trustRelationshipItem' + example: + id: c04e3b02-971c-4268-a701-b6c01468ca62 + type: send + request_type: send + state: trusted + created_at: '2023-08-19T03:40:38.200Z' + updated_at: '2023-08-19T03:40:38.200Z' + originating_wallet: testuser + actor_wallet: testuser + target_wallet: testWallet11 '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' + '415': + $ref: '#/components/responses/UnsupportedMediaTypeError' '/trust_relationships/{trust_relationship_id}/decline': post: tags: - Trust relationships - summary: Decline a trust relationship + summary: 'Decline a trust relationship' parameters: - $ref: '#/components/parameters/treetrackerApiKeyParam' - $ref: '#/components/parameters/contentTypeJsonHeader' - name: trust_relationship_id in: path - description: the id of the entity trust record on the server + description: 'The ID of the entity trust record on the server' required: true style: simple schema: - type: integer + type: string + format: uuid + example: 03537683-5356-42f4-97b2-95ba287a453f responses: '200': - description: '' + description: 'Trust relationship state is changed to `cancelled_by_target`' + content: + application/json: + schema: + $ref: '#/components/schemas/trustRelationshipItem' + example: + id: c04e3b02-971c-4268-a701-b6c01468ca62 + type: send + request_type: send + state: cancelled_by_target + created_at: '2023-08-19T03:40:38.200Z' + updated_at: '2023-08-19T03:40:38.200Z' + originating_wallet: testuser + actor_wallet: testuser + target_wallet: testWallet11 '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' + '415': + $ref: '#/components/responses/UnsupportedMediaTypeError' components: parameters: treetrackerApiKeyParam: @@ -1482,13 +1522,18 @@ components: type: object properties: trust_request_type: - type: string + $ref: '#/components/schemas/trustRequestType' requester_wallet: type: string - description: 'This is optional, if ignore it, then the default requester_wallet should be the current logged in wallet' + description: 'Optional. If not present, then the default requester_wallet will be the current logged in wallet' + example: wallet1 requestee_wallet: type: string - description: The wallet to who this request are targetting + description: 'The wallet to which this request is targeted.' + example: testwallet + required: + - trust_request_type + - requestee_wallet historyResponse: title: History Response type: object @@ -1800,6 +1845,31 @@ components: originating_wallet: testuser source_wallet: testuser destination_wallet: wallet2 + trustRelationshipRequestedResponse: + description: 'Accepted but waiting for approval' + content: + application/json: + schema: + $ref: '#/components/schemas/trustRelationshipItem' + example: + id: d4b785f8-25eb-41ff-bf77-3dfd7312756d + type: manage + request_type: manage + state: requested + created_at: '2023-09-01T01:45:16.213Z' + updated_at: '2023-09-01T01:45:16.213Z' + originating_wallet: wallet1 + actor_wallet: wallet1 + target_wallet: otherwallet + trustRelationshipNotFound: + description: 'No trust relationship found matching trust_relationship_id or it is not associated with the logged in wallet' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + code: 404 + message: 'Cannot find wallet_trust by id:d4b785f8-25eb-41ff-bf77-3dfd7312756e' securitySchemes: httpBearer: type: http From 2b1cb0773a2e18532828a10529fb2d78dd6b8859 Mon Sep 17 00:00:00 2001 From: Pranav Kakaraparti Date: Thu, 31 Aug 2023 16:18:13 -0500 Subject: [PATCH 12/12] feat: remove unused components --- docs/api/spec/treetracker-token-api.yaml | 129 ----------------------- 1 file changed, 129 deletions(-) diff --git a/docs/api/spec/treetracker-token-api.yaml b/docs/api/spec/treetracker-token-api.yaml index e57b0dbc..aed0a46d 100644 --- a/docs/api/spec/treetracker-token-api.yaml +++ b/docs/api/spec/treetracker-token-api.yaml @@ -1331,28 +1331,6 @@ components: bundle_size: 100 sender_wallet: wallet1 receiver_wallet: wallet2 - transferbundlerequest: - title: transferbundlerequest - required: - - parameters - - sender_wallet - - receiver_wallet - type: object - properties: - parameters: - $ref: '#/components/schemas/requestBundleRequestParameters' - sender_wallet: - oneOf: - - type: string - - type: number - receiver_wallet: - oneOf: - - type: string - - type: number - example: - bundle_size: 500 - sender_wallet: zaven - receiver_wallet: GreenEarthAppeal transferItem: title: Transfer Details properties: @@ -1415,91 +1393,6 @@ components: - managed example: send description: 'The type of transfer. The value is computed by the server based on the submitted request' - sendrequest: - title: sendrequest - required: - - tokens - - receiver_wallet - type: object - properties: - tokens: - type: array - items: - type: string - description: '' - receiver_wallet: - oneOf: - - type: string - - type: number - example: - tokens: - - e1b278e8-f025-44b7-9dd8-36ffb2d58f7e - - e533653e-2dbf-48cd-940a-a87e5a393158 - receiver_wallet: zaven - sendBundleRequest: - title: sendBundleRequest - type: object - properties: - parameters: - $ref: '#/components/schemas/requestBundleRequestParameters' - receiver_wallet: - type: string - required: - - bundle_size - - receiver_wallet - pendingTransfersResponse: - title: List of Pending Transfers - type: object - properties: - pending: - type: array - items: - $ref: '#/components/schemas/pendingTransferItem' - pendingTransferItem: - title: Pending Transfer Item - type: object - properties: - id: - type: integer - sender_wallet: - type: string - receiver_wallet: - type: string - created_at: - type: string - requestBundleRequest: - title: requestBundleRequest - type: object - properties: - parameters: - $ref: '#/components/schemas/requestBundleRequestParameters' - sender_wallet: - type: string - description: Senders other than the wallet requesting the transfer are not allowed at this time - receiver_wallet: - type: string - required: - - params - - receiver_wallet - requestBundleRequestParameters: - title: Parameters for Transfer Request - type: object - properties: - tokens: - type: array - items: - type: string - description: optional array of explicit tokens - bundle_size: - type: integer - description: required number of trees to transfer - matching_all_tags: - type: array - items: - type: string - description: optional list of tags that trees must match ALL of - required: - - bundle_size requestBundleFulfillBody: title: Transfer Request Fulfillment type: object @@ -1561,28 +1454,6 @@ components: sender_wallet: zaven receiver_wallet: zaven2 processed_at: '2020-01-17T22:32:43.008Z' - eventStream: - title: Event Stream - type: object - properties: - events: - type: array - items: - $ref: '#/components/schemas/eventItem' - eventItem: - title: Event Item - type: object - properties: - type: - type: string - wallet: - type: string - transfer_id: - type: integer - trust_relationship_id: - type: integer - created_at: - type: string trustRelationshipsResponse: title: Trust Relationships Response type: object