1. Using Oracle Blockchain Platform
  2. Build Chaincodes with Low-Code Blockchain App Builder
  3. Using the Blockchain App Builder Command Line Interface
  4. Generate a Postman Collection Using the CLI

Generate a Postman Collection Using the CLI

You can use the generate command to create a Postman collection that includes example payloads for all of your chaincode controller APIs.

Postman is a tool that you can use to work with and test REST APIs. The generate command creates a Postman collection that is based on the chaincode that was automatically generated from a declarative specification file. The Postman collection contains the payloads for all of the methods that are specified in the chaincode controller file. You can change the variable values in the Postman collection file to make REST API calls.

The generated Postman collection includes default values for all APIs in the controller. To learn more about Postman, see https://www.postman.com/. After you generate a Postman collection, you can directly import it and use it by changing the default values in the payload and variables.

Usage:

generate [options]
my-mac:TsProject myname$ ochain generate -h 
Usage: generate [options]

Generates the postman collection for the chaincode. 

Options :
    -h, --help              output command usage information
    -D, --debug             enable debug logging
    -c, --collection        This option is mandatory to generate a Postman collection.
    -p, --project <path>    Path to the chaincode project to generate the Postman collection from. If not specified, it defaults to current directory.
    -o, --out <path>        Path to the generated Postman collection JSON file. If not specified, it defaults to current directory.

To generate a Postman collection, navigate to the directory that contains the project and then enter the following command. You must run the generate command from the chaincode directory or an error will occur. If the specified Postman collection already exists, you are prompted whether to overwrite it. 

ochain generate --collection --project path_to_chaincode_project --out path_to_postman_collection_to_generate

Postman Collection Structure

The generated Postman collection includes two types of requests, invoke requests and query requests:
  • Invoke requests include all write operations, which use the endpoint /transactions
  • Query requests include all get operations, which use the endpoint /chaincode-queries

To differentiate between getter and non-getter methods in the controller APIs, a decorator is used in TypeScript chaincodes and a comment is used in Go chaincodes. If you define a getter method in the controller, you must use the GetMethod decorator for TypeScript or the GetMethod comment for Go, as shown in the following table.

TypeScript Go
Every getter method has a GetMethod decorator:
@GetMethod()
@Validator()
public async getAllTokenAdmins() {
  await this.Ctx.ERC1155Auth.checkAuthorization("ERC1155ADMIN.getAllAdmins", "TOKEN");
  return await this.Ctx.ERC1155Admin.getAllAdmins();
}
 Every getter method has a GetMethod comment block:
/**
 * GetMethod
 */
func (t *Controller) GetAllTokenAdmins() (interface{}, error) {
    auth, err := t.Ctx.Auth.CheckAuthorization("Admin.GetAllAdmins", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    return t.Ctx.Admin.GetAllTokenAdmins()
}

Generated Postman collections include variables with default values, as shown in the following table.

Variable Name Description Default Value Context
bc-url The REST proxy URL of the Oracle Blockchain Platform instance where the chaincode is deployed https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy all chaincodes
bc-channel The channel where the chaincode is deployed default all chaincodes
bc-admin-user The name of the admin user (a user with the admin role that can access all POST requests). By default, this user is the caller of all POST requests in the chaincode bc-admin-user value all chaincodes
bc-admin-password The password for the admin user bc-admin-password value all chaincodes
bc-timeout The timeout value in the body of every POST request to indicate the timeout interval 6000 all chaincodes
bc-sync The sync value in the body of every POST request to indicate whether the request is synchronous or asynchronous true all chaincodes
bc-chaincode-name The chaincode name, which is used in every POST request chaincode name all chaincodes
bc-org-id The default orgId parameter for all POST requests bc-org-id value token chaincodes only
bc-user-id The default userId parameter for all POST requests bc-user-id value token chaincodes only
bc-token-id The default tokenId parameter for all POST requests bc-token-id value token chaincodes only

In every generated request, all of the parameters with default values are generated. Functions that have struct/class parameters will have a placeholder object in the request body, as shown in the following examples.

API with a struct/class parameter 
{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "CreateArtCollectionToken",
        "{\"TokenId\":\"{{bc-token-id}}\",\"TokenDesc\":\"TokenDesc value\",\"TokenUri\":\"TokenUri value\",\"TokenMetadata\":{\"Painting_name\":\"Painting_name value\",\"Description\":\"Description value\",\"Image\":\"Image value\",\"Painter_name\":\"Painter_name value\"},\"Price\":999,\"On_sale_flag\":true}",
        "quantity value"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}
API without a struct/class parameter 
{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "CreateAccount",
        "{{bc-org-id}}",
        "example_minter",
        "true",
        "true"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}

The default value for most API parameters is parameter_name value, with some exceptions. The following examples show some of the exceptions.

  • The filters parameter in GetAccountTransactionHistoryWithFilters: 
    "{\"PageSize\":20,\"Bookmark\":\"\",\"StartTime\":\"2022-01-16T15:16:36+00:00\",\"EndTime\":\"2022-01-17T15:16:36+00:00\"}"
  • The filters parameter in GetSubTransactionsByIdWithFilters:
    "{\"PageSize\":20,\"Bookmark\":\"\}"

A struct or class has different default values, as shown in the following table:

Data Type Default Value
boolean/bool true
int/number 999
date 2022-01-16T15:16:36+00:00
other parameter_name value

ERC-1155 Token Projects

The ERC-1155 standard includes common methods for both fungible and non-fungible tokens. The generated Postman collection for an ERC-1155 project that uses both fungible and non-fungible tokens includes two different POST requests, one for each type of token, for these common methods. If an ERC-1155 project uses only fungible or non-fungible tokens but not both types, then the generated Postman collection includes only one POST request for these common methods. The following table illustrates the generated API for the AddRole method.
  Fungible Tokens Non-Fungible Tokens
Request Name AddRole -For Fungible AddRole -For NonFungible
Request Body 
{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "AddRole",
        "{{bc-org-id}}",
        "{{bc-user-id}}",
        "role value (for example, minter / burner)",
        "{\"TokenId\":\"{{bc-token-id}}\"}"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}
 
{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "AddRole",
        "{{bc-org-id}}",
        "{{bc-user-id}}",
        "role value (for example, minter / burner)",
        "{\"TokenName\":\"TokenName value\"}"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}