Generate a Postman Collection Using Visual Studio Code

You can 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.

To generate a Postman collection for a chaincode project in Visual Studio Code, complete the following steps.

1. Select the chaincode project in the Chaincodes pane.
2. Right-click the chaincode name and then select Generate Postman Collection.
3. Select a location to save the Postman collection to, and then click Select Output Folder.

If the specified Postman collection already exists, you are prompted whether to overwrite it.

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}} }