Deploy Wrapper APIs

Oracle Blockchain Platform Digital Assets Edition can generate wrapper APIs for all controller APIs in chaincode generated by Blockchain App Builder. Complete the following steps to deploy the wrapper API package in the stack resource manager and to test the wrapper APIs by using the associated Postman collection.

When you generate a wrapper API package using Blockchain App Builder, it creates two files with default naming conventions in the chosen directory:

  • <ChaincodeName>WrapperAPI.zip: An archive file that contains the Terraform script required to deploy the wrapper APIs in Oracle Cloud Infrastructure (OCI) Resource Manager.
  • <ChaincodeName>_WrapperAPI.postman_collection.json: A Postman collection used to test the wrapper APIs after deployment.

To deploy the wrapper APIs, you use the WrapperAPI.zip file to create a stack in OCI Resource Manager.

The following prerequisites must be met to deploy the wrapper API package.

  • The wrapper API package must be generated using Blockchain App Builder.
  • The package must include all required configuration variable values and endpoint values for the wrapper APIs.
  1. Log in to OCI.
    Open the OCI console and sign in: https://cloud.oracle.com/. Ensure that you're in the compartment where the stack will be deployed.
  2. Expand the Navigation menu. Select Developer Services. Under Resource Manager, select Stacks.
    The Resource Manager interface for stacks opens. You can view existing stacks, create stacks, and manage your infrastructure as code using Terraform configurations.
  3. Click Create Stack.
  4. Configure the stack information.
    1. In the Terraform Configuration section, select My Configuration.
    2. In Stack Configuration, Terraform configuration source, select .Zip file.
    3. Click Browse and navigate to your wrapper API .zip file.
    4. After the .zip file is uploaded, ensure that the stack name is correct.
    5. In the Terraform version drop-down list, select v1.2 or higher. By default, Resource Manager uses the latest version. If you select a version earlier than v1.2, the deployment will fail.
    6. All remaining settings can be kept as default. Click Next.
  5. Configure the stack variables.
    1. Verify that all configuration variable values are accurate and align with the configuration variables specified in the wrapper API package to meet the requirements for your deployment.
    2. For ocir_user_name, enter the email address associated with your OCI account.
    3. For ocir_user_password enter your password, which is your OCI auth token. You can generate this token in the profile or user settings section of the OCI console. The auth token functions as a password for logging into the Oracle Cloud Infrastructure Registry.
      For more information about generating an auth token, see Generating an Auth Token.
    4. All remaining settings can be kept as default. Click Next.
  6. Review the stack information. If everything is correct, click Create.
  7. Run the Terraform plan.
    1. On the stack's Details page, click Plan to start creating an execution plan.
    2. Optionally, configure the job plan. You can edit the default name or select advanced options to change the provider version or adjust settings.
    3. Click Plan to create and run the plan job.
      Your Terraform configuration is parsed and an execution plan is generated and run, which completes the following tasks:
      • Validates the Terraform script to ensure there are no syntax or configuration errors.
      • Simulates the resource creation process without making any changes to the actual infrastructure.
      • Provides an output summary that lists the resources the script will create, modify, or destroy.
    4. Monitor the status in the Jobs section of your stack. After the plan completes successfully, review the output to confirm the number of resources that will be created and to verify that there are no issues.
  8. Apply the Terraform plan to the stack.
    1. On the stack's Details page, click Apply.
    2. In the Terraform Apply panel, click Apply.
      Applying the Terraform plan completes the following tasks:
      • Provisions all of the following resources as defined in the Terraform script:
        • Virtual cloud network (VCN)
        • Applications (OCI Functions)
        • API Gateway
        • API deployment
        • IAM policy
        • OCI Registry repository
      • Creates all of the required infrastructure for the wrapper APIs.
    3. Monitor the status in the Jobs section of your stack to ensure the job completes successfully with no errors.
  9. Retrieve the API Gateway endpoints.
    1. After the apply job completes, go to the Outputs section of the Apply job page to view the generated output values.
    2. The output returns a JSON object where the keys represent endpoint names and the values are their corresponding endpoint values:
      api_gateway_endpoints{"api_gateway_endpoint":"https://grqkdiwsugp3fp2m5z3zgpo4.apigateway.ap-mumbai-1.oci.customer-oci.com/WholesaleCBDC"}
    3. Copy the endpoint. You need the endpoint to update the API Postman collection.
Testing Wrapper APIs with Postman

You can test the wrapper APIs by using Postman. Configure all of the variables in the wrapper API Postman collection by assigning the appropriate values. Get the api_gateway_endpoint value from the output of the stack deployment in OCI, where the dynamically generated gateway endpoints are provided.

After the variables in the Postman collection are updated, you can test the wrapper APIs. Each API request in the collection includes the necessary payload specific to the corresponding wrapper API.

Figure 4-1 Testing an API Wrapper Collection with Postman


Image shows Postman running an API from the collection using the generated gateway API.

The following information can be used to troubleshoot problems when deploying and using wrapper APIs.

Unauthorized: Invalid ocir_user_name or ocir_user_password
This error occurs when either the user name or password credentials are incorrect. To resolve this issue, follow these steps:
  1. Navigate to the Variables section in the stack Details page.
  2. Click Edit Variables to modify the user name and password values.
  3. Update the credentials with the correct information.
  4. Click Apply to redeploy the stack.
Deployment Failure - "denied: Anonymous users are only allowed read access on public repos"
Occasionally, the deployment might fail with the following error:
denied: Anonymous users are only allowed read access on public repos

This is an intermittent issue that is related to Docker operations in the stack's back end. Specifically, this error occurs when attempting to push Docker images to the Oracle Cloud Infrastructure Registry without proper authentication.

While the wrapper API package includes a script that runs the docker login command to ensure proper authentication before pushing the images, this error can still occur sporadically. It typically happens when the Docker authentication step is not properly recognized by the system at the time of image push.

If this error occurs, follow these steps to resolve the issue:

  1. Click Destroy in the OCI Stack Resource Manager to destroy all of the resources that were created during the deployment process.
  2. After the resources are destroyed, click Apply again to redeploy the stack. This triggers the creation of the necessary resources including proper Docker authentication.
Generic Deployment Failure: Intermittent Issues
Stack deployment can fail sometimes due to random Docker-related issues. When this happens, follow these steps to resolve the issue:
  1. Click Destroy to remove all of the resources that were created during the failed deployment.
  2. After the resources are destroyed, navigate back to the stack and click Apply to redeploy the stack.

This can resolve intermittent issues and allow for a successful deployment.