From aa7650a5de991cd1aa5713aa72b85e0d7dd449e8 Mon Sep 17 00:00:00 2001 From: Julian Ospald Date: Mon, 19 Oct 2020 17:22:26 +0200 Subject: [PATCH] Document endpoints error codes in the API documentation --- specifications/api/swagger.yaml | 658 ++++++++++++++++++++++++++++---- 1 file changed, 588 insertions(+), 70 deletions(-) diff --git a/specifications/api/swagger.yaml b/specifications/api/swagger.yaml index 4d446dfcfb6..e126c4cb041 100644 --- a/specifications/api/swagger.yaml +++ b/specifications/api/swagger.yaml @@ -1840,12 +1840,363 @@ x-responsesErr: &responsesErr description: A specific error code for this error, more precise than HTTP ones. example: an_error_code +x-responsesErrWalletNotFound: &responsesErrWalletNotFound + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['no_such_wallet'] + +x-responsesErrBadRequest: &responsesErrBadRequest + type: object + required: + - message + - code + properties: + message: + type: string + description: Explanation of a good request. + code: + type: string + enum: ['bad_request'] + +x-responsesErrNotJson: &responsesErrNotJson + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive message explaining the expected media type is JSON. + code: + type: string + enum: ['unsupported_media_type'] + +x-responsesErrNotOctetStream: &responsesErrNotOctetStream + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive message explaining the expected media type is octet stream. + code: + type: string + enum: ['unsupported_media_type'] + +x-responsesErrNotAcceptable: &responsesErrNotAcceptable + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive message explaining acceptable headers. + code: + type: string + enum: ['not_acceptable'] + +x-responsesErrWalletAlreadyExists: &responsesErrWalletAlreadyExists + type: object + required: + - message + - code + properties: + message: + type: string + description: Explanation of wallet with conflicting id. + code: + type: string + enum: ['wallet_already_exists'] + +x-errWithRootKeyNoRootKey: &errWithRootKeyNoRootKey + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['no_root_key'] + +x-errWithRootKeyWrongPassphrase: &errWithRootKeyWrongPassphrase + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['wrong_encryption_passphrase'] + +x-errInvalidWalletType: &errInvalidWalletType + type: object + required: + - message + - code + properties: + message: + type: string + description: Explanation of a valid wallet type. + code: + type: string + enum: ['invalid_wallet_type'] + +x-errAlreadyWithdrawing: &errAlreadyWithdrawing + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['already_withdrawing'] + +x-errTransactionIsTooBig: &errTransactionIsTooBig + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['transaction_is_too_big'] + +x-errUTxOTooSmall: &errUTxOTooSmall + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['utxo_too_small'] + +x-errCannotCoverFee: &errCannotCoverFee + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['cannot_cover_fee'] + +x-errNotEnoughMoney: &errNotEnoughMoney + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['not_enough_money'] + +x-errInputsDepleted: &errInputsDepleted + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['inputs_depleted'] + +x-errInvalidSelection: &errInvalidSelection + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['invalid_coin_selection'] + +x-errWithRootKey: &errWithRootKey + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['no_root_key'] + +x-errMinWithdrawalWrong: &errMinWithdrawalWrong + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['min_withdrawal_wrong'] + +x-errStartTimeLaterThanEndTime: &errStartTimeLaterThanEndTime + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['start_time_later_than_end_time'] + +x-errTransactionNotPending: &errTransactionNotPending + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['transaction_not_pending'] + +x-errNoSuchTransaction: &errNoSuchTransaction + type: object + required: + - message + - code + properties: + message: + type: string + description: A message describing the transaction ID that could not be found. + code: + type: string + enum: ['no_such_transaction'] + +x-errQueryParamMissing: &errQueryParamMissing + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['query_param_missing'] + +x-errNotDelegating: &errNotDelegating + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['not_delegating_to'] + +x-errNonNullRewards: &errNonNullRewards + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['non_null_rewards'] + +x-errAlreadyDelegating: &errAlreadyDelegating + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['pool_already_joined'] + +x-errNoSuchPool: &errNoSuchPool + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['no_such_pool'] + +x-errNothingToMigrate: &errNothingToMigrate + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['nothing_to_migrate'] + x-responsesErr400: &responsesErr400 400: description: Bad Request content: application/json: - schema: *responsesErr + schema: *responsesErrBadRequest x-responsesErr403: &responsesErr403 403: @@ -1873,7 +2224,7 @@ x-responsesErr406: &responsesErr406 description: Not Acceptable content: application/json: - schema: *responsesErr + schema: *responsesErrNotAcceptable x-responsesErr409: &responsesErr409 409: @@ -1903,8 +2254,35 @@ x-responsesErr423: &responsesErr423 application/json: schema: *responsesErr +x-responsesErr404WalletNotFound: &responsesErr404WalletNotFound + 404: + description: Not Found + content: + application/json: + schema: *responsesErrWalletNotFound + +x-responsesErr409WalletAlreadyExists: &responsesErr409WalletAlreadyExists + 409: + description: Conflict + content: + application/json: + schema: *responsesErrWalletAlreadyExists + +x-responsesErr415NotJson: &responsesErr415NotJson + 415: + description: Unsupported Media Type + content: + application/json: + schema: *responsesErrNotJson + +x-responsesErr415NotOctetStream: &responsesErr415NotOctetStream + 415: + description: Unsupported Media Type + content: + application/json: + schema: *responsesErrNotOctetStream + x-responsesListWallets: &responsesListWallets - <<: *responsesErr405 <<: *responsesErr406 200: description: Ok @@ -1926,8 +2304,7 @@ x-responsesListByronWallets: &responsesListByronWallets items: *ApiByronWallet x-responsesGetUTxOsStatistics: &responsesGetUTxOsStatistics - <<: *responsesErr404 - <<: *responsesErr405 + <<: *responsesErr404WalletNotFound <<: *responsesErr406 200: description: Ok @@ -1937,10 +2314,9 @@ x-responsesGetUTxOsStatistics: &responsesGetUTxOsStatistics x-responsesPostWallet: &responsesPostWallet <<: *responsesErr400 - <<: *responsesErr405 <<: *responsesErr406 - <<: *responsesErr409 - <<: *responsesErr415 + <<: *responsesErr409WalletAlreadyExists + <<: *responsesErr415NotJson 201: description: Created content: @@ -1960,8 +2336,8 @@ x-responsesPostByronWallet: &responsesPostByronWallet schema: *ApiByronWallet x-responsesGetWallet: &responsesGetWallet - <<: *responsesErr404 - <<: *responsesErr405 + <<: *responsesErr400 + <<: *responsesErr404WalletNotFound <<: *responsesErr406 200: description: Ok @@ -1980,8 +2356,12 @@ x-responsesGetByronWallet: &responsesGetByronWallet schema: *ApiByronWallet x-responsesGetWalletMigrationInfo: &responsesGetWalletMigrationInfo - <<: *responsesErr404 - <<: *responsesErr405 + 403: + description: Forbidden + content: + application/json: + schema: *errNothingToMigrate + <<: *responsesErr404WalletNotFound <<: *responsesErr406 200: description: Ok @@ -1990,11 +2370,24 @@ x-responsesGetWalletMigrationInfo: &responsesGetWalletMigrationInfo schema: *ApiWalletMigrationInfo x-responsesMigrateWallet: &responsesMigrateWallet - <<: *responsesErr403 - <<: *responsesErr404 - <<: *responsesErr405 + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errNothingToMigrate + - <<: *errWithRootKey + - <<: *errWithRootKeyWrongPassphrase + <<: *responsesErr404WalletNotFound <<: *responsesErr406 - <<: *responsesErr415 + 410: + description: Gone + content: + application/json: + schema: + <<: *responsesErrWalletNotFound + <<: *responsesErr415NotJson 200: description: Ok content: @@ -2004,8 +2397,8 @@ x-responsesMigrateWallet: &responsesMigrateWallet items: *ApiTransaction x-responsesDeleteWallet: &responsesDeleteWallet - <<: *responsesErr404 - <<: *responsesErr405 + <<: *responsesErr400 + <<: *responsesErr404WalletNotFound <<: *responsesErr406 204: description: No Content @@ -2022,10 +2415,9 @@ x-responsesForceResyncWallet: &responsesForceResyncWallet x-responsesPutWallet: &responsesPutWallet <<: *responsesErr400 - <<: *responsesErr404 - <<: *responsesErr405 + <<: *responsesErr404WalletNotFound <<: *responsesErr406 - <<: *responsesErr415 + <<: *responsesErr415NotJson 200: description: Ok content: @@ -2034,21 +2426,38 @@ x-responsesPutWallet: &responsesPutWallet x-responsesPutWalletPassphrase: &responsesPutWalletPassphrase <<: *responsesErr400 - <<: *responsesErr403 - <<: *responsesErr404 - <<: *responsesErr405 + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errWithRootKeyNoRootKey + - <<: *errWithRootKeyWrongPassphrase + <<: *responsesErr404WalletNotFound <<: *responsesErr406 - <<: *responsesErr415 + <<: *responsesErr415NotJson 204: description: No Content x-responsesSelectCoins: &responsesSelectCoins <<: *responsesErr400 - <<: *responsesErr403 - <<: *responsesErr404 - <<: *responsesErr405 + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errAlreadyWithdrawing + - <<: *errUTxOTooSmall + - <<: *errNotEnoughMoney + - <<: *errCannotCoverFee + - <<: *errInputsDepleted + - <<: *errTransactionIsTooBig + - <<: *errInvalidSelection + <<: *responsesErr404WalletNotFound <<: *responsesErr406 - <<: *responsesErr415 + <<: *responsesErr415NotJson 200: description: OK content: @@ -2056,16 +2465,33 @@ x-responsesSelectCoins: &responsesSelectCoins schema: *ApiCoinSelection x-responsesDeleteTransaction: &responsesDeleteTransaction - <<: *responsesErr403 - <<: *responsesErr404 - <<: *responsesErr405 + 403: + description: Forbidden + content: + application/json: + schema: *errTransactionNotPending + 404: + description: Not Found + content: + application/json: + schema: + oneOf: + - <<: *responsesErrWalletNotFound + - <<: *errNoSuchTransaction <<: *responsesErr406 204: description: No Content x-responsesListTransactions: &responsesListTransactions - <<: *responsesErr404 - <<: *responsesErr405 + 400: + description: Bad Request + content: + application/json: + schema: + oneOf: + - <<: *errMinWithdrawalWrong + - <<: *errStartTimeLaterThanEndTime + <<: *responsesErr404WalletNotFound <<: *responsesErr406 200: description: Ok @@ -2081,8 +2507,14 @@ x-responsesListTransactions: &responsesListTransactions items: *ApiTransaction x-responsesGetTransaction: &responsesGetTransaction - <<: *responsesErr404 - <<: *responsesErr405 + 404: + description: Not Found + content: + application/json: + schema: + oneOf: + - <<: *responsesErrWalletNotFound + - <<: *errNoSuchTransaction <<: *responsesErr406 200: description: OK @@ -2091,12 +2523,37 @@ x-responsesGetTransaction: &responsesGetTransaction schema: *ApiTransaction x-responsesPostTransaction: &responsesPostTransaction - <<: *responsesErr400 - <<: *responsesErr403 - <<: *responsesErr404 - <<: *responsesErr405 + 400: + description: Bad Request + content: + application/json: + schema: + oneOf: + - <<: *responsesErrBadRequest + - <<: *errTransactionIsTooBig + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errInvalidWalletType + - <<: *errAlreadyWithdrawing + - <<: *errUTxOTooSmall + - <<: *errCannotCoverFee + - <<: *errNotEnoughMoney + - <<: *errTransactionIsTooBig + - <<: *errWithRootKey + - <<: *errWithRootKeyWrongPassphrase + <<: *responsesErr404WalletNotFound <<: *responsesErr406 - <<: *responsesErr415 + 410: + description: Gone + content: + application/json: + schema: + <<: *responsesErrWalletNotFound + <<: *responsesErr415NotJson 202: description: Accepted content: @@ -2105,9 +2562,8 @@ x-responsesPostTransaction: &responsesPostTransaction x-responsesPostExternalTransaction: &responsesPostExternalTransaction <<: *responsesErr400 - <<: *responsesErr405 <<: *responsesErr406 - <<: *responsesErr415 + <<: *responsesErr415NotOctetStream 202: description: Accepted content: @@ -2115,12 +2571,31 @@ x-responsesPostExternalTransaction: &responsesPostExternalTransaction schema: *ApiTxId x-responsesPostTransactionFee: &responsesPostTransactionFee - <<: *responsesErr400 - <<: *responsesErr403 - <<: *responsesErr404 - <<: *responsesErr405 + 400: + description: Bad Request + content: + application/json: + schema: + oneOf: + - <<: *responsesErrBadRequest + - <<: *errTransactionIsTooBig + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errInvalidWalletType + - <<: *errAlreadyWithdrawing + - <<: *errUTxOTooSmall + - <<: *errCannotCoverFee + - <<: *errNotEnoughMoney + - <<: *errInputsDepleted + - <<: *errInvalidSelection + - <<: *errTransactionIsTooBig + <<: *responsesErr404WalletNotFound <<: *responsesErr406 - <<: *responsesErr415 + <<: *responsesErr415NotJson 202: description: Accepted content: @@ -2128,9 +2603,12 @@ x-responsesPostTransactionFee: &responsesPostTransactionFee schema: *ApiFee x-responsesGetDelegationFee: &responsesGetDelegationFee - <<: *responsesErr403 - <<: *responsesErr404 - <<: *responsesErr405 + 403: + description: Forbidden + content: + application/json: + schema: *errCannotCoverFee + <<: *responsesErr404WalletNotFound <<: *responsesErr406 200: description: Ok @@ -2140,8 +2618,7 @@ x-responsesGetDelegationFee: &responsesGetDelegationFee x-responsesListAddresses: &responsesListAddresses <<: *responsesErr400 - <<: *responsesErr404 - <<: *responsesErr405 + <<: *responsesErr404WalletNotFound <<: *responsesErr406 200: description: Ok @@ -2152,8 +2629,11 @@ x-responsesListAddresses: &responsesListAddresses items: *ApiAddress x-responsesListStakePools: &responsesListStakePools - <<: *responsesErr405 - <<: *responsesErr404 + 400: + description: Bad Request + content: + application/json: + schema: *errQueryParamMissing 200: description: Ok content: @@ -2169,11 +2649,32 @@ x-responsesListStakePools: &responsesListStakePools x-responsesJoinStakePool: &responsesJoinStakePool <<: *responsesErr400 - <<: *responsesErr403 - <<: *responsesErr404 - <<: *responsesErr405 + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errCannotCoverFee + - <<: *errWithRootKey + - <<: *errWithRootKeyWrongPassphrase + - <<: *errAlreadyDelegating + 404: + description: Not Found + content: + application/json: + schema: + oneOf: + - <<: *responsesErrWalletNotFound + - <<: *errNoSuchPool <<: *responsesErr406 - <<: *responsesErr415 + 410: + description: Gone + content: + application/json: + schema: + <<: *responsesErrWalletNotFound + <<: *responsesErr415NotJson 202: description: Accepted content: @@ -2181,10 +2682,34 @@ x-responsesJoinStakePool: &responsesJoinStakePool schema: *ApiTransaction x-responsesQuitStakePool: &responsesQuitStakePool - <<: *responsesJoinStakePool + <<: *responsesErr400 + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errCannotCoverFee + - <<: *errWithRootKey + - <<: *errWithRootKeyWrongPassphrase + - <<: *errNotDelegating + - <<: *errNonNullRewards + <<: *responsesErr404WalletNotFound + <<: *responsesErr406 + 410: + description: Gone + content: + application/json: + schema: + <<: *responsesErrWalletNotFound + <<: *responsesErr415NotJson + 202: + description: Accepted + content: + application/json: + schema: *ApiTransaction x-responsesGetNetworkInformation: &responsesGetNetworkInformation - <<: *responsesErr405 <<: *responsesErr406 200: description: Ok @@ -2193,7 +2718,6 @@ x-responsesGetNetworkInformation: &responsesGetNetworkInformation schema: *ApiNetworkInformation x-responsesGetNetworkClock: &responsesGetNetworkClock - <<: *responsesErr405 <<: *responsesErr406 200: description: Ok @@ -2202,7 +2726,6 @@ x-responsesGetNetworkClock: &responsesGetNetworkClock schema: *ApiNetworkClock x-responsesGetNetworkParameters: &responsesGetNetworkParameters - <<: *responsesErr405 <<: *responsesErr406 200: description: Ok @@ -2238,8 +2761,6 @@ x-responsesPutRandomAddresses: &responsesPutRandomAddresses x-responsesInspectAddress: &responsesInspectAddress <<: *responsesErr400 - <<: *responsesErr405 - <<: *responsesErr415 200: description: Ok content: @@ -2248,15 +2769,11 @@ x-responsesInspectAddress: &responsesInspectAddress x-responsesPutSettings: &responsesPutSettings <<: *responsesErr400 - <<: *responsesErr403 - <<: *responsesErr405 + <<: *responsesErr415NotJson 204: description: No Content x-responsesGetSettings: &responsesGetSettings - <<: *responsesErr400 - <<: *responsesErr403 - <<: *responsesErr405 200: description: Ok content: @@ -2537,6 +3054,7 @@ paths: get: operationId: getDelegationFee tags: ["Stake Pools"] + summary: Estimate Fee description: |

status: stable