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.
- Select the chaincode project in the Chaincodes pane.
- Right-click the chaincode name and then select Generate Postman Collection.
- 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
- 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 |
|
|