Generate a Wrapper API Specification and Postman Collection with the Command Line

You can use Blockchain App Builder to create filtered token and account/identity endpoint specification files and a matching Postman collection.

The wrapper-api-endpoints-config Hardhat task generates endpoint configuration files and a Postman collection from deployed contract artifacts or ABI files. The Postman task can also incorporate an ORDS Swagger/OpenAPI document and combined API definitions.

Prerequisites

• Install the project’s dependencies and compile if you plan to use artifacts.
• Ensure that the Wrapper API plug-in and its tasks are configured in the hardhat.config.ts file.
• Identify the token and, when applicable, account contract artifact or ABI files.

Generate an Endpoint Configuration

Run the following commands from the prepackaged contract project’s root directory. Replace the example paths and names with paths in your project.

To generate an endpoint configuration file for each contract target that you want to expose, run the following commands.

npx hardhat generate:wrapper-api-endpoints-config \
  --artifact artifacts/contracts/Token.sol/Token.json \
  --out generated/wrapper-api/token-endpoints.json

npx hardhat generate:wrapper-api-endpoints-config \
  --artifact artifacts/contracts/Account.sol/Account.json \
  --out generated/wrapper-api/account-endpoints.json

To start from an ABI file instead, replace --artifact with --abi, as shown in the following example.

npx hardhat generate:wrapper-api-endpoints-config \
  --abi ./abi/Token.json \
  --out generated/wrapper-api/token-endpoints.json

Review the generated endpoint configuration before you it, so that you can choose or refine the methods and paths that are exposed by the wrapper API.

Generate a Wrapper API Postman Collection

Pass one or more endpoint configuration files as a comma-separated value, as shown in the following example.

npx hardhat generate:wrapper-api-postman-collection \
  --inputs generated/wrapper-api/token-endpoints.json,generated/wrapper-api/account-endpoints.json \
  --out generated/wrapper-api/wrapper-api.postman.collection.json

Import the resulting collection into Postman and populate its environment variables with the URL and credentials for the deployed wrapper API.

Include an ORDS Swagger/OpenAPI file

The optional --ords-swagger argument accepts an ORDS Swagger/OpenAPI JSON file. Its GET operations are added under an ORDS Endpoints folder in the generated Postman collection and are registered as ORDS back end overrides in the generated configuration.

npx hardhat generate:wrapper-api-postman-collection \
  --inputs generated/wrapper-api/token-endpoints.json,generated/wrapper-api/account-endpoints.json \
  --ords-swagger ./api/ords.swagger.json \
  --out generated/wrapper-api/wrapper-api.postman.collection.json

Use a valid JSON Swagger/OpenAPI document. The file is not deployed by this command; it is an input used to build the wrapper API and Postman assets.

Define a Combined API

A combined API runs several contract methods in sequence through one POST endpoint. First, generate an endpoint configuration. Then ,add a combinedApis entry to that configuration, as shown in the following example.

{
  "combinedApis": [
    {
      "name": "createAccountWithRole",
      "path": "createAccountWithRole",
      "httpMethod": "POST",
      "inputs": {
        "required": ["account", "role", "userId"]
      },
      "steps": [
        { "method": "createAccount", "args": ["userId"] },
        { "method": "addRole", "args": ["account", "role"] }
      ],
      "mappings": {
        "createAccount": { "userId": "request.userId" },
        "addRole": {
          "account": "request.account",
          "role": "request.role"
        }
      }
    }
  ]
}

Merge this fragment with the generated configuration; do not replace its generated endpoint content. Use actual ABI method names and argument names from your contract. The request body supplies the named inputs as top-level fields, for example: account, role, and userId. It does not use a payload wrapper.

All steps must belong to the same target configuration. A combined API cannot mix token methods with account or identity methods. Steps run in the order that they are written. Design the sequence and failure handling with that behavior in mind. Then, generate the collection using the edited configuration, as shown in the following example.

npx hardhat generate:wrapper-api-postman-collection \
  --inputs generated/wrapper-api/account-endpoints.json \
  --out generated/wrapper-api/account-wrapper-api.postman.collection.json

Troubleshooting

Condition	Resolution
Task not found	Check that the project has the wrapper API plug-in installed and configured in the hardhat.config.ts file.
Artifact or ABI file not found	Compile the project when using the --artifact option, or correct the path passed to the --artifact or --abi options.
ORDS endpoints are missing	Verify the --ords-swagger path points to valid JSON and that the source contains supported GET operations.
Combined API validation fails	Ensure that the name, path, steps, required inputs, and mappings are present. Verify that all referenced methods belong to the same token or account/identity configuration.