Using Postman to Explore the Ledger API

Background

This page documents how to setup Postman to explore the Ledger API. You may already be familiar with using Postman to query JSON API endpoints. In 2022, Postman added support for gRPC endpoints. The Ledger API is a collection of gRPC endpoints.

These notes are based on:

  • macOS
  • Daml SDK 2.4
  • Postman Version 10.4.2
    • UI Version: 10.4.2-ui-221121-1032
    • Desktop Platform Version: 10.1.2 (10.1.2)

Compatibility Limitations

Postman’s support for gRPC is not 100% compatible with the Ledger API. For example:

  • The “server reflection” feature does not work. This is the feature that queries for the endpoints and types. Instead, you will need to point Postman to proto files for that information.

  • Postman does not work with the “server streaming” endpoints. For example, the Ledger API’s TransactionService has GetTransactions and GetTransactionTrees endpoints. These two endpoints stream results. Postman does not work with these two endpoints.

Due to these limitations, you might consider additionally Using gRPC UI to Explore the Ledger API. Both Postman and gRPC UI have their advantages.

API Setup

  1. Clone the daml repository, if you don’t already have it locally. You need this for the .proto files.

    git clone https://github.com/digital-asset/daml.git
    
  2. Start the Sandbox ledger.

    daml sandbox
    
  3. In Postman, use File → New… to create a new “gRPC Request”.

  4. For “Enter Server URL” use localhost:6865. For “Select a Method” use “Import a .proto file.”

  5. Navigate on your local drive to daml/ledger-api/grpc-definitions/com/daml/ledger/api/v1 and select VersionService.proto.

  6. Click on “Add an import path” and add daml/ledger-api/grpc-definitions ( :warning: not the full path to the v1 folder!).

  7. Click Next, enter an API name for Postman (e.g, Ledger API Version Service), and click “Import as API”.

  8. For “Select a Method” select “GetLedgerApiVersion” and press “Invoke.”

  9. View the response from the service, in JSON format.

  10. Repeat these steps for the other .proto files that you would like to use. See the Ledger API documentation for the expected message bodies for the various service endpoints.

2 Likes

Hi Wallace, that’s a great write-up.

Was this written and tested solely on MacOS?

@Ben_M Yes, I did this on a macOS. Great question. I updated the post to include that note.

You don’t happen to use a Windows machine do you?

1 Like

No, I am one of the lucky company minority using GNU/Linux :grinning:

Nice, thanks for sharing.

To clarify, “server reflection” in general should work but unfortunately breaks for the Ledger API due to a bug that is open at the time of writing. Hopefully it will be fixed in the future.

1 Like

I have done something similar on Windows and it worked. In general I would expect it to be working regardless of the underlying OS (but of course OS-specific bugs might always arise).