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
- 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:
|
Every getter method has a GetMethod comment
block:
|
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 theAddRole
method.
Fungible Tokens | Non-Fungible Tokens | |
---|---|---|
Request Name | AddRole -For Fungible |
AddRole -For NonFungible |
Request Body |
|
|