From 73b694131021c21949b6ea5733b01619722d890e Mon Sep 17 00:00:00 2001 From: Enzo Cioppettini Date: Mon, 4 Mar 2024 01:25:20 -0300 Subject: [PATCH] add missing endpoint level docs --- docs/bin/openapi.json | 9 ++++++--- .../app/controllers/AssetUtxosController.ts | 20 ++++++++++++++++--- .../DelegationForAddressController.ts | 6 ++++++ .../DelegationForPoolController.ts | 8 ++++++++ webserver/shared/models/AssetUtxos.ts | 12 +++++------ 5 files changed, 43 insertions(+), 12 deletions(-) diff --git a/docs/bin/openapi.json b/docs/bin/openapi.json index 952199da..856fa32f 100644 --- a/docs/bin/openapi.json +++ b/docs/bin/openapi.json @@ -196,7 +196,8 @@ "type": "string" }, "amount": { - "type": "string" + "type": "string", + "description": "If the utxo is created, this has the amount. It's undefined if the utxo\nis spent." } }, "required": [ @@ -209,8 +210,7 @@ ], "type": "object" }, - "type": "array", - "description": "If the utxo is created, this has the amount. It's undefined if the utxo\nis spent." + "type": "array" } }, "required": [ @@ -1473,6 +1473,7 @@ } } }, + "description": "Returns utxo entries filtered either by cip 14 fingerprint or by policy id.\n\nThis is useful to keep track of the utxo set of a particular asset.", "security": [], "parameters": [], "requestBody": { @@ -1632,6 +1633,7 @@ } } }, + "description": "Returns the pool of the last delegation for this address.\n\nNote: the tx can be in the current epoch, so the delegation may not be in\neffect yet.", "security": [], "parameters": [], "requestBody": { @@ -1691,6 +1693,7 @@ } } }, + "description": "Returns the list of delegations for the provided pools. The pool field in\nthe response will be null when the address was previously delegating to a\npool in the input, but now the delegation is moved to a pool outside the\nlist, or when the staking key is unregistered.\n\nThis is useful to keep track of the delegators for a particular pool.", "security": [], "parameters": [], "requestBody": { diff --git a/webserver/server/app/controllers/AssetUtxosController.ts b/webserver/server/app/controllers/AssetUtxosController.ts index e091cb19..81faeab1 100644 --- a/webserver/server/app/controllers/AssetUtxosController.ts +++ b/webserver/server/app/controllers/AssetUtxosController.ts @@ -11,7 +11,11 @@ import type { IAssetUtxosResult } from '../models/asset/assetUtxos.queries'; import { bech32 } from 'bech32'; import { ASSET_UTXOS_LIMIT } from '../../../shared/constants'; import { Address } from '@dcspark/cardano-multiplatform-lib-nodejs'; -import { adjustToSlotLimits, resolvePageStart, resolveUntilTransaction } from '../services/PaginationService'; +import { + adjustToSlotLimits, + resolvePageStart, + resolveUntilTransaction, +} from '../services/PaginationService'; import { slotBoundsPagination } from '../models/pagination/slotBoundsPagination.queries'; import { expectType } from 'tsd'; @@ -19,6 +23,11 @@ const route = Routes.assetUtxos; @Route('asset/utxos') export class AssetUtxosController extends Controller { + /** + * Returns utxo entries filtered either by cip 14 fingerprint or by policy id. + * + * This is useful to keep track of the utxo set of a particular asset. + */ @SuccessResponse(`${StatusCodes.OK}`) @Post() public async assetUtxos( @@ -76,7 +85,12 @@ export class AssetUtxosController extends Controller { }); } - const pageStartWithSlot = adjustToSlotLimits(pageStart, until, requestBody.slotLimits, slotBounds); + const pageStartWithSlot = adjustToSlotLimits( + pageStart, + until, + requestBody.slotLimits, + slotBounds + ); const data = await getAssetUtxos({ after: pageStartWithSlot?.tx_id || 0, @@ -135,4 +149,4 @@ export class AssetUtxosController extends Controller { return response; } -} +} \ No newline at end of file diff --git a/webserver/server/app/controllers/DelegationForAddressController.ts b/webserver/server/app/controllers/DelegationForAddressController.ts index b12d3744..4fbd8aed 100644 --- a/webserver/server/app/controllers/DelegationForAddressController.ts +++ b/webserver/server/app/controllers/DelegationForAddressController.ts @@ -15,6 +15,12 @@ const route = Routes.delegationForAddress; @Route('delegation/address') export class DelegationForAddressController extends Controller { + /** + * Returns the pool of the last delegation for this address. + * + * Note: the tx can be in the current epoch, so the delegation may not be in + * effect yet. + */ @SuccessResponse(`${StatusCodes.OK}`) @Post() public async delegationForAddress( diff --git a/webserver/server/app/controllers/DelegationForPoolController.ts b/webserver/server/app/controllers/DelegationForPoolController.ts index b7f7d14a..7379efb3 100644 --- a/webserver/server/app/controllers/DelegationForPoolController.ts +++ b/webserver/server/app/controllers/DelegationForPoolController.ts @@ -20,6 +20,14 @@ const route = Routes.delegationForPool; @Route('delegation/pool') export class DelegationForPoolController extends Controller { + /** + * Returns the list of delegations for the provided pools. The pool field in + * the response will be null when the address was previously delegating to a + * pool in the input, but now the delegation is moved to a pool outside the + * list, or when the staking key is unregistered. + * + * This is useful to keep track of the delegators for a particular pool. + */ @SuccessResponse(`${StatusCodes.OK}`) @Post() public async delegationForPool( diff --git a/webserver/shared/models/AssetUtxos.ts b/webserver/shared/models/AssetUtxos.ts index c35d2577..e76c82a8 100644 --- a/webserver/shared/models/AssetUtxos.ts +++ b/webserver/shared/models/AssetUtxos.ts @@ -18,13 +18,13 @@ export type AssetUtxosRequest = { } & Pagination; export type AssetUtxosResponse = { - /** - * If the utxo is created, this has the amount. It's undefined if the utxo - * is spent. - * - * @example '1031423725351' - */ payload: { + /** + * If the utxo is created, this has the amount. It's undefined if the utxo + * is spent. + * + * @example '1031423725351' + */ amount: string | undefined; cip14Fingerprint: string; policyId: string;