Wrapper API Package Components

Wrapper API packages contain an archive file of the wrapper APIs, a Terraform script for deployment, and a corresponding Postman collection.

The wrapper API archive file is named <ChaincodeName>WrapperAPI.zip. It also contains a Terraform script that must be deployed to the stack resource.
The Postman collection file is named <ChaincodeName>_WrapperAPI.postman_collection.json. You can use this collection to call all of the wrapper APIs.

Wrapper API Package

The wrapper API package contains a Terraform script that provisions all of the Oracle Cloud Infrastructure (OCI) resources that are necessary for creating the wrapper APIs. There are additional Terraform support files and an Oracle Functions folder for each API. The wrapper API packages creates the following OCI resources.

Virtual Cloud Network (VCN): Establishes the network infrastructure for communication.
Applications (Oracle Functions): Deploys serverless functions to handle API logic.
API Gateway: Creates the gateway to manage and route API requests.
API Deployment: Configures and deploys the APIs on the API Gateway.
API Deployment Policy: Sets up the necessary IAM policies to enable secure access.
OCI Registry: Provides a container registry for managing Docker images.

After you generate wrapper APIs, if you want to change any configuration variables, you can update them in Visual Studio Code, or you can extract the wrapper API package and update the terraform.tfvars file with updated endpoints and resource names and the routes.go file with updated endpoints. Edit the function_paths variable in the terraform.tfvars file to update an endpoint. The function_paths variable defines endpoints with the following syntax: {endpoint, methodType}. The following text shows an example of a function_paths variable.

function_paths="[{\"endpoint\":\"/activateCBDCAccount\",\"methodType\":[\"POST\"]},{\"endpoint\":\"/addCBAdmin\",\"methodType\":[\"POST\"]},{\"endpoint\":\"/approveBurn\",\"methodType\":[\"POST\"]}]"

The routes.go file is in the <ChaincodeName>OCIFunction folder. The routeData variable contains metadata for all routes created in the gateway, including the route name, arguments, and whether there are optional arguments. When you update an endpoint in the function_paths variable in the terraform.tfvars file, you must also updat the corresponding entry in the routeData variable in the routes.go file, as shown in the following example.

var routeData = map[string]Route{
    "/activateCBDCAccount": {
        Args:           []string{"activateAccount", "orgId", "userId", "tokenId"},
        OptionalParams: true,
    },
}

Postman Collection

Postman collections now support confidential chaincode and OAuth 2.0 authentication. For more information, see Enhancements to Postman Collections.

The Postman collection includes updated endpoints and payloads for all APIs. The following code shows an example payload.

{
    "orgId": "{{bc-org-id}}",
    "userId": "user1",
    "tokenType": "fungible",
    "applicationGroups": "[\"application_groups value\"]",
    "dailyLimits": "{\"max_daily_amount\":10000,\"max_daily_transactions\":100}",
    "endorsers": {{endorsers}}
}

The following table shows the Postman collection variables.

Variable	Description	Default value
`bc-admin-user`	The administrative user, who has the `admin` role and can access all POST requests. By default, this user is the caller of all POST requests in the chaincode.	`bc-admin-user value`
`bc-admin-user-password`	Administrative user password.	`bc-admin-user-password value`
`bc-org-id`	The default organization ID in all POST requests where `orgId` is the parameter name	`bc-org-id value`
`bc-user-id`	The default user ID in all POST requests where `userId` is the parameter name	`bc-user-id value`
`bc-token-id`	The default token ID in all POST requests where `tokenId` is the parameter name	`bc-token-id value`
`endorsers`	The endorsers array lists the specific peers (for example: peer1, peer2) to endorse this transaction.	`["org1-xyz-abc.blockchain.ocp.oraclecloud.com:20009", "org2-xyz-abc.blockchain.ocp.oraclecloud.com:20009"]`
`api-gateway-endpoint`	The endpoint of each request, which serves as a base path for wrapper API endpoints. If there are fewer than 50 APIs, a single endpoint is used. If there are more than 50 APIs, the endpoints are dynamically generated as `api-gateway-endpoint1`, `api-gateway-endpoint2`, and so on, based on the number of APIs.	`https://xyz.apigateway.region.oci.customer-oci.com/CBDC`
`bc-url`	The REST proxy URL of the Oracle Blockchain Platform instance.	`https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy`
`access-token-url`	The Oracle Identity Cloud Service (IDCS) access token URL. For example: `<idcs_endpoint>/oauth/v1/token`	`access-token-url value`
`client-id`	The client ID of the Oracle Blockchain Platform instance.	`client-id`
`client-secret`	The client secret of the Oracle Blockchain Platform instance.	`client-secret`
`peer`	This variable exists only for the confidential chaincode wrapper API Postman collection, which requires the peer header for all setter and getter APIs.	`org-xyz-abc.blockchain.ocp.oraclecloud.com:20009`

After you deploy the wrapper API package, the output from the stack resource deployment is a JSON object that contains the gateway endpoint values. If you generate more than 50 APIs, multiple gateway endpoints are generated, one for every 50 APIs. You must update the Postman collection variables related to these endpoints. The endpoint-related variables in the Postman collection must be updated with the appropriate values from the output of the wrapper API package deployment in the Stack Resource Manager.

All setter APIs in the wrapper API Postman collection include either the endorsers or sameOrgEndorser parameter in the request payload. The information that specifies which APIs require the sameOrgEndorser parameter is defined in the sameOrgEndorserOptionInWrapperAPI parameter in the .ochain.json file in the chaincode. APIs listed in this parameter will have sameOrgEndorser set to true in their payloads. All other setter APIs will include the endorsers parameter instead. The following example shows the parameter for the wholesale CBDC chaincode.

"sameOrgEndorserOptionInWrapperAPI": ["addConversionRate","addTokenAdmin","addTokenAuditor","approveBurn","approveMint","burnTokens","createExchangePoolAccounts","deleteHistoricalTransactions","initializeCBDCToken","initializeExchangePoolUser","mintWithFundingExchangePool","rejectBurn","rejectMint","removeTokenAdmin","removeTokenAuditor","requestBurn","requestMint","updateCBDCToken","updateConversionRate"]

You can customize the sameOrgEndorserOptionInWrapperAPI parameter in the .ochain.json file as needed. When you generate wrapper APIs, the specified APIs will then include the sameOrgEndorser parameter as true in their payloads.

For more details about using Postman collections, see the following topics.