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 invoke 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. Edit the function_paths variable the terraform.tfvars file to update an endpoint. The function_paths variable is a JSON object where the key is the API name and the value is another JSON object with the following two keys:

path: Defines the endpoint for the API
type: Specifies the request type (POST or GET)

The following text shows an example of a function_paths variable.

function_paths="{\"activateAccount\":{\"path\":\"/activateAccount\",\"type\":[\"POST\"]}}"

Postman Collection

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 admin user, which has admin role where it has access to 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`	Admin 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`
`peer`	This variable exists only for the confidential chaincode wrapper API Postman collection, which requires the peer header for all setter 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.