Merge pull request #1521 from hyperledger/confirm-docs

Document the confirm option on the generated invoke APIs
hyperledger · Jun 17, 2024 · c2c5a95 · c2c5a95
2 parents 001e542 + 56d344c
commit c2c5a95
Show file tree

Hide file tree

Showing 25 changed files with 54 additions and 48 deletions.
diff --git a/doc-site/docs/swagger/swagger.yaml b/doc-site/docs/swagger/swagger.yaml
@@ -5069,7 +5069,8 @@ paths:
       description: Invokes a method on a smart contract. Performs a blockchain transaction.
       operationId: postContractInvoke
       parameters:
-      - description: When true the HTTP request blocks until the message is confirmed
+      - description: When true the HTTP request blocks until the blockchain transaction
+          is confirmed
         in: query
         name: confirm
         schema:
@@ -17476,7 +17477,8 @@ paths:
         schema:
           example: default
           type: string
-      - description: When true the HTTP request blocks until the message is confirmed
+      - description: When true the HTTP request blocks until the blockchain transaction
+          is confirmed
         in: query
         name: confirm
         schema:

diff --git a/internal/apiserver/ffi2swagger.go b/internal/apiserver/ffi2swagger.go
@@ -1,4 +1,4 @@
-// Copyright © 2023 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -89,6 +89,9 @@ func addFFIMethod(ctx context.Context, routes []*ffapi.Route, method *fftypes.FF
 		Name:   fmt.Sprintf("invoke_%s", method.Pathname),
 		Path:   fmt.Sprintf("invoke/%s", method.Pathname), // must match a route defined in apiserver routes!
 		Method: http.MethodPost,
+		QueryParams: []*ffapi.QueryParam{
+			{Name: "confirm", Description: coremsgs.APIConfirmInvokeQueryParam, IsBool: true, Example: "true"},
+		},
 		JSONInputSchema: func(ctx context.Context, schemaGen ffapi.SchemaGenerator) (*openapi3.SchemaRef, error) {
 			return contractRequestJSONSchema(ctx, &method.Params, hasLocation)
 		},

diff --git a/internal/apiserver/route_patch_update_identity.go b/internal/apiserver/route_patch_update_identity.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -33,7 +33,7 @@ var patchUpdateIdentity = &ffapi.Route{
 		{Name: "iid", Description: coremsgs.APIParamsIdentityID},
 	},
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true},
 	},
 	Description:     coremsgs.APIEndpointsPatchUpdateIdentity,
 	JSONInputValue:  func() interface{} { return &core.IdentityUpdateDTO{} },

diff --git a/internal/apiserver/route_post_contract_api_invoke.go b/internal/apiserver/route_post_contract_api_invoke.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -35,7 +35,7 @@ var postContractAPIInvoke = &ffapi.Route{
 		{Name: "methodPath", Description: coremsgs.APIParamsMethodPath},
 	},
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true, Example: "true"},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true, Example: "true"},
 	},
 	Description:     coremsgs.APIEndpointsPostContractAPIInvoke,
 	JSONInputValue:  func() interface{} { return &core.ContractCallRequest{} },

diff --git a/internal/apiserver/route_post_contract_api_publish.go b/internal/apiserver/route_post_contract_api_publish.go
@@ -1,4 +1,4 @@
-// Copyright © 2023 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -34,7 +34,7 @@ var postContractAPIPublish = &ffapi.Route{
 		{Name: "apiName", Description: coremsgs.APIParamsContractAPIName},
 	},
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true},
 	},
 	Description:     coremsgs.APIEndpointsPostContractAPIPublish,
 	JSONInputValue:  func() interface{} { return &core.DefinitionPublish{} },

diff --git a/internal/apiserver/route_post_contract_deploy.go b/internal/apiserver/route_post_contract_deploy.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -32,7 +32,7 @@ var postContractDeploy = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true, Example: "true"},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true, Example: "true"},
 	},
 	Description:     coremsgs.APIEndpointsPostContractDeploy,
 	JSONInputValue:  func() interface{} { return &core.ContractDeployRequest{} },

diff --git a/internal/apiserver/route_post_contract_interface_publish.go b/internal/apiserver/route_post_contract_interface_publish.go
@@ -1,4 +1,4 @@
-// Copyright © 2023 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -35,7 +35,7 @@ var postContractInterfacePublish = &ffapi.Route{
 		{Name: "version", Description: coremsgs.APIParamsContractInterfaceVersion},
 	},
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true},
 	},
 	Description:     coremsgs.APIEndpointsPostContractInterfacePublish,
 	JSONInputValue:  func() interface{} { return &core.DefinitionPublish{} },

diff --git a/internal/apiserver/route_post_contract_invoke.go b/internal/apiserver/route_post_contract_invoke.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -32,7 +32,7 @@ var postContractInvoke = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true, Example: "true"},
+		{Name: "confirm", Description: coremsgs.APIConfirmInvokeQueryParam, IsBool: true, Example: "true"},
 	},
 	Description:     coremsgs.APIEndpointsPostContractInvoke,
 	JSONInputValue:  func() interface{} { return &core.ContractCallRequest{} },

diff --git a/internal/apiserver/route_post_new_contract_api.go b/internal/apiserver/route_post_new_contract_api.go
@@ -1,4 +1,4 @@
-// Copyright © 2023 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -32,7 +32,7 @@ var postNewContractAPI = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true, Example: "true"},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true, Example: "true"},
 		{Name: "publish", Description: coremsgs.APIPublishQueryParam, IsBool: true},
 	},
 	Description:     coremsgs.APIEndpointsPostNewContractAPI,

diff --git a/internal/apiserver/route_post_new_contract_interface.go b/internal/apiserver/route_post_new_contract_interface.go
@@ -1,4 +1,4 @@
-// Copyright © 2023 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -32,7 +32,7 @@ var postNewContractInterface = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true, Example: "true"},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true, Example: "true"},
 		{Name: "publish", Description: coremsgs.APIPublishQueryParam, IsBool: true},
 	},
 	Description:     coremsgs.APIEndpointsPostNewContractInterface,

diff --git a/internal/apiserver/route_post_new_datatype.go b/internal/apiserver/route_post_new_datatype.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -31,7 +31,7 @@ var postNewDatatype = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true, Example: "true"},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true, Example: "true"},
 	},
 	Description:     coremsgs.APIEndpointsPostNewDatatype,
 	JSONInputValue:  func() interface{} { return &core.Datatype{} },

diff --git a/internal/apiserver/route_post_new_identity.go b/internal/apiserver/route_post_new_identity.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -31,7 +31,7 @@ var postNewIdentity = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true},
 	},
 	Description:     coremsgs.APIEndpointsPostNewIdentity,
 	JSONInputValue:  func() interface{} { return &core.IdentityCreateDTO{} },

diff --git a/internal/apiserver/route_post_new_message_broadcast.go b/internal/apiserver/route_post_new_message_broadcast.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -32,7 +32,7 @@ var postNewMessageBroadcast = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true},
 	},
 	Description:     coremsgs.APIEndpointsPostNewMessageBroadcast,
 	JSONInputValue:  func() interface{} { return &core.MessageInOut{} },

diff --git a/internal/apiserver/route_post_new_message_private.go b/internal/apiserver/route_post_new_message_private.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -32,7 +32,7 @@ var postNewMessagePrivate = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true},
 	},
 	Description:     coremsgs.APIEndpointsPostNewMessagePrivate,
 	JSONInputValue:  func() interface{} { return &core.MessageInOut{} },

diff --git a/internal/apiserver/route_post_new_node_self.go b/internal/apiserver/route_post_new_node_self.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -32,7 +32,7 @@ var postNodesSelf = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true, Example: "true"},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true, Example: "true"},
 	},
 	Description:     coremsgs.APIEndpointsPostNodesSelf,
 	JSONInputValue:  func() interface{} { return &core.EmptyInput{} },

diff --git a/internal/apiserver/route_post_new_organization.go b/internal/apiserver/route_post_new_organization.go
@@ -1,4 +1,4 @@
-// Copyright © 2023 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -32,7 +32,7 @@ var postNewOrganization = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true, Example: "true"},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true, Example: "true"},
 	},
 	Description:     coremsgs.APIEndpointsPostNewOrganization,
 	JSONInputValue:  func() interface{} { return &core.IdentityCreateDTO{} },

diff --git a/internal/apiserver/route_post_new_organization_self.go b/internal/apiserver/route_post_new_organization_self.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -32,7 +32,7 @@ var postNewOrganizationSelf = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true, Example: "true"},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true, Example: "true"},
 	},
 	Description:     coremsgs.APIEndpointsPostNewOrganizationSelf,
 	JSONInputValue:  func() interface{} { return &core.EmptyInput{} },

diff --git a/internal/apiserver/route_post_token_approval.go b/internal/apiserver/route_post_token_approval.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -31,7 +31,7 @@ var postTokenApproval = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true},
 	},
 	Description: coremsgs.APIEndpointsPostTokenApproval,
 	JSONInputValue: func() interface{} {

diff --git a/internal/apiserver/route_post_token_burn.go b/internal/apiserver/route_post_token_burn.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -31,7 +31,7 @@ var postTokenBurn = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true},
 	},
 	Description:     coremsgs.APIEndpointsPostTokenBurn,
 	JSONInputValue:  func() interface{} { return &core.TokenTransferInput{} },

diff --git a/internal/apiserver/route_post_token_mint.go b/internal/apiserver/route_post_token_mint.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -31,7 +31,7 @@ var postTokenMint = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true},
 	},
 	Description:     coremsgs.APIEndpointsPostTokenMint,
 	JSONInputValue:  func() interface{} { return &core.TokenTransferInput{} },

diff --git a/internal/apiserver/route_post_token_pool.go b/internal/apiserver/route_post_token_pool.go
@@ -1,4 +1,4 @@
-// Copyright © 2023 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -31,7 +31,7 @@ var postTokenPool = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true},
 		{Name: "publish", Description: coremsgs.APIPublishQueryParam, IsBool: true},
 	},
 	Description:     coremsgs.APIEndpointsPostTokenPool,

diff --git a/internal/apiserver/route_post_token_pool_publish.go b/internal/apiserver/route_post_token_pool_publish.go
@@ -1,4 +1,4 @@
-// Copyright © 2023 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -33,7 +33,7 @@ var postTokenPoolPublish = &ffapi.Route{
 		{Name: "nameOrId", Description: coremsgs.APIParamsTokenPoolNameOrID},
 	},
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true},
 	},
 	Description:     coremsgs.APIEndpointsPostTokenPoolPublish,
 	JSONInputValue:  func() interface{} { return &core.DefinitionPublish{} },

diff --git a/internal/apiserver/route_post_token_transfer.go b/internal/apiserver/route_post_token_transfer.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -31,7 +31,7 @@ var postTokenTransfer = &ffapi.Route{
 	Method:     http.MethodPost,
 	PathParams: nil,
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true},
 	},
 	Description:     coremsgs.APIEndpointsPostTokenTransfer,
 	JSONInputValue:  func() interface{} { return &core.TokenTransferInput{} },

diff --git a/internal/apiserver/route_put_contract_api.go b/internal/apiserver/route_put_contract_api.go
@@ -1,4 +1,4 @@
-// Copyright © 2022 Kaleido, Inc.
+// Copyright © 2024 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -35,7 +35,7 @@ var putContractAPI = &ffapi.Route{
 		{Name: "id", Example: "id", Description: coremsgs.APIParamsContractAPIName},
 	},
 	QueryParams: []*ffapi.QueryParam{
-		{Name: "confirm", Description: coremsgs.APIConfirmQueryParam, IsBool: true, Example: "true"},
+		{Name: "confirm", Description: coremsgs.APIConfirmMsgQueryParam, IsBool: true, Example: "true"},
 	},
 	Description:     coremsgs.APIParamsContractAPIID,
 	JSONInputValue:  func() interface{} { return &core.ContractAPI{} },

diff --git a/internal/coremsgs/en_api_translations.go b/internal/coremsgs/en_api_translations.go
@@ -202,7 +202,8 @@ var (
 	APIFilterLimitDesc         = ffm("api.filterLimit", "The maximum number of records to return (max: %d)")
 	APIFilterCountDesc         = ffm("api.filterCount", "Return a total count as well as items (adds extra database processing)")
 	APIFetchDataDesc           = ffm("api.fetchData", "Fetch the data and include it in the messages returned")
-	APIConfirmQueryParam       = ffm("api.confirmQueryParam", "When true the HTTP request blocks until the message is confirmed")
+	APIConfirmMsgQueryParam    = ffm("api.confirmMsgQueryParam", "When true the HTTP request blocks until the message is confirmed")
+	APIConfirmInvokeQueryParam = ffm("api.confirmInvokeQueryParam", "When true the HTTP request blocks until the blockchain transaction is confirmed")
 	APIPublishQueryParam       = ffm("api.publishQueryParam", "When true the definition will be published to all other members of the multiparty network")
 	APIHistogramStartTimeParam = ffm("api.histogramStartTime", "Start time of the data to be fetched")
 	APIHistogramEndTimeParam   = ffm("api.histogramEndTime", "End time of the data to be fetched")