From d9bcf5417c52dad4d9bd057b9d92f5e7c0f4c40d Mon Sep 17 00:00:00 2001 From: KtorZ Date: Wed, 16 Oct 2019 13:40:27 +0200 Subject: [PATCH] better organize swagger documentations by grouping tags (byron vs shelley) Also renamed '/byron/wallets' to '/byron-wallets' to better reflect what the resource should be --- .../src/Test/Integration/Framework/DSL.hs | 18 ++-- .../Integration/Scenario/API/ByronWallets.hs | 19 ++-- lib/core/src/Cardano/Wallet/Api.hs | 46 +++++----- lib/core/src/Cardano/Wallet/Api/Server.hs | 4 +- .../Jormungandr/Scenario/API/Transactions.hs | 4 +- specifications/api/swagger.yaml | 88 +++++++++++-------- 6 files changed, 102 insertions(+), 77 deletions(-) diff --git a/lib/core-integration/src/Test/Integration/Framework/DSL.hs b/lib/core-integration/src/Test/Integration/Framework/DSL.hs index f0f803da9a3..43118707b2d 100644 --- a/lib/core-integration/src/Test/Integration/Framework/DSL.hs +++ b/lib/core-integration/src/Test/Integration/Framework/DSL.hs @@ -989,9 +989,9 @@ tearDown ctx = do d <- request @Value ctx ("DELETE", endpoint) None Empty expectResponseCode HTTP.status204 d respByron <- - request @[ApiByronWallet] ctx ("GET", "v2/byron/wallets") Default Empty + request @[ApiByronWallet] ctx ("GET", "v2/byron-wallets") Default Empty forM_ (wallets (snd respByron)) $ \wal -> do - let endpoint = "v2/byron/wallets" wal ^. walletId + let endpoint = "v2/byron-wallets" wal ^. walletId d <- request @Value ctx ("DELETE", endpoint) None Empty expectResponseCode HTTP.status204 d where @@ -1055,37 +1055,37 @@ networkInfoEp = postByronWalletEp :: (Method, Text) postByronWalletEp = ( "POST" - , "v2/byron/wallets" + , "v2/byron-wallets" ) listByronWalletEp :: (Method, Text) listByronWalletEp = ( "GET" - , "v2/byron/wallets" + , "v2/byron-wallets" ) migrateByronWalletEp :: ApiByronWallet -> ApiWallet -> (Method, Text) migrateByronWalletEp wSrc wDest = ( "POST" - , "v2/byron/wallets/" <> wSrc ^. walletId <> "/migrate/" <> wDest ^. walletId + , "v2/byron-wallets/" <> wSrc ^. walletId <> "/migrations/" <> wDest ^. walletId ) calculateByronMigrationCostEp :: ApiByronWallet -> (Method, Text) calculateByronMigrationCostEp w = ( "GET" - , "v2/byron/wallets/" <> w ^. walletId <> "/migrate" + , "v2/byron-wallets/" <> w ^. walletId <> "/migrations" ) getByronWalletEp :: ApiByronWallet -> (Method, Text) getByronWalletEp w = ( "GET" - , "v2/byron/wallets/" <> w ^. walletId + , "v2/byron-wallets/" <> w ^. walletId ) deleteByronWalletEp :: ApiByronWallet -> (Method, Text) deleteByronWalletEp w = ( "DELETE" - , "v2/byron/wallets/" <> w ^. walletId + , "v2/byron-wallets/" <> w ^. walletId ) listStakePoolsEp :: (Method, Text) @@ -1103,7 +1103,7 @@ postWalletEp = postExternalTxEp :: (Method, Text) postExternalTxEp = ( "POST" - , "v2/external-transactions" + , "v2/proxy/transactions" ) getWalletEp :: ApiWallet -> (Method, Text) diff --git a/lib/core-integration/src/Test/Integration/Scenario/API/ByronWallets.hs b/lib/core-integration/src/Test/Integration/Scenario/API/ByronWallets.hs index a4bff8d45e5..420edd28ddc 100644 --- a/lib/core-integration/src/Test/Integration/Scenario/API/ByronWallets.hs +++ b/lib/core-integration/src/Test/Integration/Scenario/API/ByronWallets.hs @@ -78,21 +78,26 @@ spec :: forall t. (EncodeAddress t, DecodeAddress t) => SpecWith (Context t) spec = do describe "BYRON_ESTIMATE_06 - non-existing wallets" $ do - forM_ falseWalletIds $ \(desc, walId) -> it desc $ \ctx -> do - let endpoint = "v2/byron/wallets/" <> T.pack walId <> "/migrate" + forM_ (take 1 falseWalletIds) $ \(desc, walId) -> it desc $ \ctx -> do + let endpoint = "v2/byron-wallets/" <> T.pack walId <> "/migrations" + rg <- request @ApiByronWallet ctx ("GET", endpoint) Default Empty + expectResponseCode @IO HTTP.status501 rg + + forM_ (drop 1 falseWalletIds) $ \(desc, walId) -> it desc $ \ctx -> do + let endpoint = "v2/byron-wallets/" <> T.pack walId <> "/migrations" rg <- request @ApiByronWallet ctx ("GET", endpoint) Default Empty expectResponseCode @IO HTTP.status404 rg expectErrorMessage errMsg404NoEndpoint rg it "BYRON_GET_02 - Byron ep does not show new wallet" $ \ctx -> do w <- emptyWallet ctx - let ep = ( "GET", "v2/byron/wallets/" <> w ^. walletId ) + let ep = ( "GET", "v2/byron-wallets/" <> w ^. walletId ) r <- request @ApiByronWallet ctx ep Default Empty expectResponseCode @IO HTTP.status404 r describe "BYRON_GET_06 - non-existing wallets" $ do forM_ falseWalletIds $ \(desc, walId) -> it desc $ \ctx -> do - let endpoint = "v2/byron/wallets/" <> T.pack walId + let endpoint = "v2/byron-wallets/" <> T.pack walId rg <- request @ApiByronWallet ctx ("GET", endpoint) Default Empty if (desc == valid40CharHexDesc) then do expectErrorMessage (errMsg404NoWallet $ T.pack walId) rg @@ -107,13 +112,13 @@ spec = do it "BYRON_DELETE_02 - Byron ep does not delete new wallet" $ \ctx -> do w <- emptyWallet ctx - let ep = ( "DELETE", "v2/byron/wallets/" <> w ^. walletId ) + let ep = ( "DELETE", "v2/byron-wallets/" <> w ^. walletId ) r <- request @ApiByronWallet ctx ep Default Empty expectResponseCode @IO HTTP.status404 r describe "BYRON_DELETE_04 - non-existing wallets" $ do forM_ falseWalletIds $ \(desc, walId) -> it desc $ \ctx -> do - let endpoint = "v2/byron/wallets/" <> T.pack walId + let endpoint = "v2/byron-wallets/" <> T.pack walId rg <- request @ApiByronWallet ctx ("DELETE", endpoint) Default Empty if (desc == valid40CharHexDesc) then do expectErrorMessage (errMsg404NoWallet $ T.pack walId) rg @@ -496,7 +501,7 @@ spec = do describe "BYRON_RESTORE_07 - v2/wallets - Methods Not Allowed" $ do let matrix = ["PUT", "DELETE", "CONNECT", "TRACE", "OPTIONS"] forM_ matrix $ \method -> it (show method) $ \ctx -> do - r <- request @ApiByronWallet ctx (method, "v2/byron/wallets") Default Empty + r <- request @ApiByronWallet ctx (method, "v2/byron-wallets") Default Empty expectResponseCode @IO HTTP.status405 r expectErrorMessage errMsg405 r diff --git a/lib/core/src/Cardano/Wallet/Api.hs b/lib/core/src/Cardano/Wallet/Api.hs index fa677ceb988..e2e92be7f84 100644 --- a/lib/core/src/Cardano/Wallet/Api.hs +++ b/lib/core/src/Cardano/Wallet/Api.hs @@ -233,11 +233,6 @@ type ListTransactions t = "wallets" :> QueryParam "order" (ApiT SortOrder) :> Get '[JSON] [ApiTransaction t] --- | https://input-output-hk.github.io/cardano-wallet/api/#operation/postExternalTransaction -type PostExternalTransaction = "external-transactions" - :> ReqBody '[OctetStream] PostExternalTransactionData - :> PostAccepted '[JSON] ApiTxId - {------------------------------------------------------------------------------- StakePools @@ -261,50 +256,57 @@ type Network = :> "information" :> Get '[JSON] ApiNetworkInformation +{------------------------------------------------------------------------------- + Proxy + + See also: https://input-output-hk.github.io/cardano-wallet/api/edge/#tag/Proxy +-------------------------------------------------------------------------------} + +-- | https://input-output-hk.github.io/cardano-wallet/api/#operation/postExternalTransaction +type PostExternalTransaction = "proxy" + :> "transactions" + :> ReqBody '[OctetStream] PostExternalTransactionData + :> PostAccepted '[JSON] ApiTxId + {------------------------------------------------------------------------------- Compatibility API See also: https://input-output-hk.github.io/cardano-wallet/api/#tag/Byron-Wallets -------------------------------------------------------------------------------} +-- | https://input-output-hk.github.io/cardano-wallet/api/#operation/postByronWallet +type PostByronWallet = "byron-wallets" + :> ReqBody '[JSON] ByronWalletPostData + :> PostAccepted '[JSON] ApiByronWallet + -- | https://input-output-hk.github.io/cardano-wallet/api/#operation/deleteByronWallet -type DeleteByronWallet = "byron" - :> "wallets" +type DeleteByronWallet = "byron-wallets" :> Capture "walletId" (ApiT WalletId) :> DeleteNoContent '[Any] NoContent -- | https://input-output-hk.github.io/cardano-wallet/api/#operation/getByronWallet -type GetByronWallet = "byron" - :> "wallets" +type GetByronWallet = "byron-wallets" :> Capture "walletId" (ApiT WalletId) :> Get '[JSON] ApiByronWallet -- | https://input-output-hk.github.io/cardano-wallet/api/#operation/getByronWalletMigrationInfo -type GetByronWalletMigrationInfo = "byron" - :> "wallets" +type GetByronWalletMigrationInfo = "byron-wallets" :> Capture "walletId" (ApiT WalletId) + :> "migrations" :> Get '[JSON] ApiByronWalletMigrationInfo -- | https://input-output-hk.github.io/cardano-wallet/api/#operation/listByronWallets -type ListByronWallets = "byron" - :> "wallets" +type ListByronWallets = "byron-wallets" :> Get '[JSON] [ApiByronWallet] -- | https://input-output-hk.github.io/cardano-wallet/api/#operation/migrateByronWallet -type MigrateByronWallet t = "byron" - :> "wallets" +type MigrateByronWallet t = "byron-wallets" :> Capture "sourceWalletId" (ApiT WalletId) - :> "migrate" + :> "migrations" :> Capture "targetWalletId" (ApiT WalletId) :> ReqBody '[JSON] ApiMigrateByronWalletData :> PostAccepted '[JSON] [ApiTransaction t] --- | https://input-output-hk.github.io/cardano-wallet/api/#operation/postByronWallet -type PostByronWallet = "byron" - :> "wallets" - :> ReqBody '[JSON] ByronWalletPostData - :> PostAccepted '[JSON] ApiByronWallet - {------------------------------------------------------------------------------- Internals -------------------------------------------------------------------------------} diff --git a/lib/core/src/Cardano/Wallet/Api/Server.hs b/lib/core/src/Cardano/Wallet/Api/Server.hs index bc3a7bc5245..fbf413756d9 100644 --- a/lib/core/src/Cardano/Wallet/Api/Server.hs +++ b/lib/core/src/Cardano/Wallet/Api/Server.hs @@ -184,7 +184,7 @@ import Data.Generics.Internal.VL.Lens import Data.Generics.Labels () import Data.List - ( sortOn ) + ( isSubsequenceOf, sortOn ) import Data.Maybe ( fromMaybe, isJust ) import Data.Proxy @@ -1327,7 +1327,7 @@ instance LiftHandler (Request, ServantErr) where ] 415 -> let cType = - if "external-transactions" `elem` (pathInfo req) + if ["proxy", "transactions"] `isSubsequenceOf` pathInfo req then "application/octet-stream" else "application/json" in apiError err' UnsupportedMediaType $ mconcat diff --git a/lib/jormungandr/test/integration/Test/Integration/Jormungandr/Scenario/API/Transactions.hs b/lib/jormungandr/test/integration/Test/Integration/Jormungandr/Scenario/API/Transactions.hs index 5013374d0cb..b564ac6f394 100644 --- a/lib/jormungandr/test/integration/Test/Integration/Jormungandr/Scenario/API/Transactions.hs +++ b/lib/jormungandr/test/integration/Test/Integration/Jormungandr/Scenario/API/Transactions.hs @@ -277,7 +277,7 @@ spec = do ] describe "TRANS_EXTERNAL_CREATE_04 - \ - \v2/external-transactions - Methods Not Allowed" $ do + \v2/proxy/transactions - Methods Not Allowed" $ do let matrix = ["PUT", "DELETE", "CONNECT", "TRACE", "OPTIONS", "GET"] forM_ matrix $ \method -> it (show method) $ \ctx -> do @@ -289,7 +289,7 @@ spec = do let payload = (NonJson . BL.fromStrict . toRawBytes Base16) txBlob let headers = Headers [ ("Content-Type", "application/octet-stream") ] - let endpoint = "v2/external-transactions" + let endpoint = "v2/proxy/transactions" r <- request @ApiTxId ctx (method, endpoint) headers payload expectResponseCode @IO HTTP.status405 r expectErrorMessage errMsg405 r diff --git a/specifications/api/swagger.yaml b/specifications/api/swagger.yaml index 353afaff6dc..d32ca71b9eb 100644 --- a/specifications/api/swagger.yaml +++ b/specifications/api/swagger.yaml @@ -962,6 +962,24 @@ x-responsesGetNetworkInformation: &responsesGetNetworkInformation # # ############################################################################# +x-tagGroups: + - name: Shelley (Sequential) + tags: + - Wallets + - Addresses + - Transactions + - Stake Pools + + - name: Byron (Random) + tags: + - Byron Wallets + - Byron Migrations + + - name: Miscellaneous + tags: + - Network + - Proxy + paths: /wallets: get: @@ -1137,21 +1155,6 @@ paths: schema: *ApiPostTransactionFeeData responses: *responsesPostTransactionFee - /external-transactions: - post: - operationId: postExternalTransaction - tags: ["Transactions"] - summary: Submit External Transaction - consumes: ["application/octet-stream"] - description: | -

status: stable

- - Submits a transaction that was created and signed outside of cardano-wallet. - parameters: - - <<: *parametersBody - schema: *signedTransactionBlob - responses: *responsesPostExternalTransaction - /wallets/{walletId}/addresses: get: operationId: listAddresses @@ -1208,22 +1211,13 @@ paths: schema: *parametersQuitStakePool responses: *responsesQuitStakePool - /network/information: - get: - operationId: getNetworkInformation - tags: ["Network"] - summary: Information - description: | -

status: provisional

- responses: *responsesGetNetworkInformation - - /byron/wallets: + /byron-wallets: get: operationId: listByronWallets tags: ["Byron Wallets"] summary: List description: | -

status: not implemented

+

status: under testing

Return a list of known Byron wallets, ordered from oldest to newest. responses: *responsesListByronWallets @@ -1233,7 +1227,7 @@ paths: tags: ["Byron Wallets"] summary: Restore description: | -

status: not implemented

+

status: under testing

Restore a Byron wallet from a mnemonic sentence. parameters: @@ -1241,13 +1235,13 @@ paths: schema: *ApiByronWalletPostData responses: *responsesPostByronWallet - /byron/wallets/{walletId}: + /byron-wallets/{walletId}: get: operationId: getByronWallet tags: ["Byron Wallets"] summary: Get description: | -

status: not implemented

+

status: under testing

Return information about a Byron wallet. parameters: @@ -1259,18 +1253,18 @@ paths: tags: ["Byron Wallets"] summary: Delete description: | -

status: not implemented

+

status: under testing

Delete a Byron wallet. parameters: - *parametersWalletId responses: *responsesDeleteWallet - /byron/wallets/{walletId}/migrate: + /byron-wallets/{walletId}/migrations: get: operationId: getByronWalletMigrationInfo - tags: ["Byron Wallets"] - summary: Calculate Migration Cost + tags: ["Byron Migrations"] + summary: Calculate Cost description: |

status: not implemented

@@ -1280,10 +1274,10 @@ paths: - *parametersWalletId responses: *responsesGetByronWalletMigrationInfo - /byron/wallets/{sourceWalletId}/migrate/{targetWalletId}: + /byron-wallets/{sourceWalletId}/migrations/{targetWalletId}: post: operationId: migrateByronWallet - tags: ["Byron Wallets"] + tags: ["Byron Migrations"] summary: Migrate description: |

status: not implemented

@@ -1297,3 +1291,27 @@ paths: - <<: *parametersBody schema: *ApiMigrateByronWalletData responses: *responsesMigrateByronWallet + + /network/information: + get: + operationId: getNetworkInformation + tags: ["Network"] + summary: Information + description: | +

status: stable

+ responses: *responsesGetNetworkInformation + + /proxy/transactions: + post: + operationId: postExternalTransaction + tags: ["Proxy"] + summary: Submit External Transaction + consumes: ["application/octet-stream"] + description: | +

status: stable

+ + Submits a transaction that was created and signed outside of cardano-wallet. + parameters: + - <<: *parametersBody + schema: *signedTransactionBlob + responses: *responsesPostExternalTransaction