Interact with Hiro APIs Directly in Documentation

This feature generates language-specific client code allowing developers to seamlessly integrate API requests into their applications. With this new addition, we aim to streamline code development and accelerate the shipping process, all while providing a seamless and convenient user experience.

We’ve rolled out this feature for all of our APIs, including:

• Stacks Blockchain API
• Token Metadata API‍
• Ordinals API

This feature empowers developers to make real API requests directly from the documentation and receive live responses in real-time.

We use the site Docusaurus for Hiro documentation, and this demo panel is one of their many great out-of-the-box plugins. This new feature comes with numerous benefits for you, including:

Auto-Generated Language-Specific Client Code

Let this feature handle the heavy lifting for you. It automatically generates client code in the programming language of your choice (cURL, Python, Node, or Go), saving time and effort.

Efficient Error Handling

Users can observe how the API responds to different inputs directly in docs, allowing for better error handling and troubleshooting in a controlled environment.

Seamless Experimentation with Query and Optional Parameters

This demo panel makes it incredibly easy to experiment with different options and query parameters for specific endpoints. Say goodbye to manual trial and error in the terminal. Now, you can fine-tune your queries directly in documentation, speeding up the development process.

Select Network

As part of these parameters, you can also easily toggle between various networks, be it your local device, testnet, or mainnet.

‍

Step by Step Walkthrough

Using this new feature is easy and efficient. You can use the following steps to start building:

1.  Navigate to the official API documentation at **https://docs.hiro.so/stacks/api**.
2. Explore the documentation to identify the desired endpoints and their corresponding HTTP methods.
3. For endpoints requiring input data, find sample request payloads or parameters and fill in the required data.
4. Click the Execute button associated with your chosen endpoint to trigger the API request.
5. Review the real-time response on the same page, including the HTTP status code and data in JSON format.
6. Modify input data to experiment with different scenarios.

Example Walkthrough

This section walks you through this demo panel with an example API endpoint that retrieves a list of details for transactions for a given transaction ID or a list of transaction ID’s. Follow the steps below:

1. Navigate to the API documentation page to use this feature.
2. To the right of the API documentation, you’ll see that the endpoint is auto-populated in the endpoint field.
3. Next, in the Query parameters section, use the transaction id for the field tx_id to pass it as a query parameter. You can find an example tx_id in docs that you can use directly in the demo panel.
4. You can expand the Show optional parameters section to view the optional parameters available. Note that the parameters are already populated, so only the value can be entered in the respective fields.
5. You can choose a network to reach the endpoint between localhost, testnet and mainnet.
6. You can explore the client-generated code in different languages cURL, Node, Go, Python and then select Execute.
7. If the tx_id is valid, you’ll see the output with a list of transactions below:
   

 {
  "0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0": {
    "found": true,
    "result": {
      "tx_id": "0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0",
      "nonce": 0,
      "fee_rate": "10000",
      "sender_address": "SP2E787TXF0F50QF2GNSR11176Q19GE9AW3AA2NV3",
      "sponsored": false,
      "post_condition_mode": "deny",
      "post_conditions": [
        {
          "type": "stx",
          "condition_code": "sent_equal_to",
          "amount": "2000000",
          "principal": {
            "type_id": "principal_standard",
            "address": "SP2E787TXF0F50QF2GNSR11176Q19GE9AW3AA2NV3"
          }
        }
      ],
      "anchor_mode": "any",
      "is_unanchored": false,
      "block_hash": "0x789f220623de1c1e5e6a8ad6abfc2c45d5e9d2806582e494292ee54d6470ff2e",
      "parent_block_hash": "0xf31b3193ea9abcf4c3162ab17b9611c11b5580330946ae9b81572ecefb3fb035",
      "block_height": 69057,
      "burn_block_time": 1658776389,
      "burn_block_time_iso": "2022-07-25T19:13:09.000Z",
      "parent_burn_block_time": 1658776082,
      "parent_burn_block_time_iso": "2022-07-25T19:08:02.000Z",
      "canonical": true,
      "tx_index": 13,
      "tx_status": "success",
      "tx_result": {
        "hex": "0x070100000000000000000000000000010e51",
        "repr": "(ok u69201)"
      },
      "microblock_hash": "0x974d813f44ac60908027dc3ced8a7761f66c593a40685a64a20883063da2b817",
      "microblock_sequence": 1,
      "microblock_canonical": true,
      "event_count": 1,
      "events": [
        {
          "event_index": 0,
          "event_type": "stx_asset",
          "tx_id": "0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0",
          "asset": {
            "asset_event_type": "burn",
            "sender": "SP2E787TXF0F50QF2GNSR11176Q19GE9AW3AA2NV3",
            "recipient": "",
            "amount": "2000000"
          }
        }
      ],
      "execution_cost_read_count": 8,
      "execution_cost_read_length": 41871,
      "execution_cost_runtime": 57781,
      "execution_cost_write_count": 2,
      "execution_cost_write_length": 149,
      "tx_type": "contract_call",
      "contract_call": {
        "contract_id": "SP000000000000000000002Q6VF78.bns",
        "function_name": "name-preorder",
        "function_signature": "(define-public (name-preorder (hashed-salted-fqn (buff 20)) (stx-to-burn uint)))",
        "function_args": [
          {
            "hex": "0x0200000014c707a319fa0b3b082553b8b662ef30cc9d2126fa",
            "repr": "0xc707a319fa0b3b082553b8b662ef30cc9d2126fa",
            "name": "hashed-salted-fqn",
            "type": "(buff 20)"
          },
          {
            "hex": "0x01000000000000000000000000001e8480",
            "repr": "u2000000",
            "name": "stx-to-burn",
            "type": "uint"
          }
        ]
      }
    }
  }
}

If the tx_id is invalid, you’ll see an error like this:

{
  "0x0a411719e3bfde95f9e227a2d8fac3d6c646b1e6cc186db0e2838a2c6cd9c0": {
    "found": false,
    "result": {
      "tx_id": "0x0a411719e3bfde95f9e227a2d8fac3d6c646b1e6cc186db0e2838a2c6cd9c0"
    }
  }
}

Let Us Know What You Think

Our goal is to help you ship faster, and we hope this new feature makes Hiro docs a more interactive experience that helps you learn more quickly. You can check out this new feature in the reference docs for our APIs here:

• Stacks Blockchain API
• Token Metadata API
• Ordinals API

If you're a visual learner, you can watch Lavanya demo this new feature in docs on our YouTube channel:

‍

We'd love to hear your feedback on this feature and on docs in general. Please reach out to us on the hiro-documentation channel on Discord or file a GitHub issue.