Interact with Hiro APIs Directly in Documentation

We're excited to announce the launch of our latest feature in Hiro docs, a demo panel to interact with APIs. Now, you can interact with API endpoints directly from documentation, making testing and experimentation easier than ever before.

Type
Product update
Topic(s)
Docs
Published
August 11, 2023
Author(s)
Technical Writer
An image of the interactive API box in docs
Contents

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:

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

A screenshot of the new interactive API box in docs

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.

A screenshot of the specific code options

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.

A screenshot of the error handling

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.

A screenshot showing customization options

Select Network

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

A screenshot of network options

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:

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.

Product updates & dev resources straight to your inbox
Your Email is in an invalid format
Checkbox is required.
Thanks for
subscribing.
Oops! Something went wrong while submitting the form.
Copy link
Mailbox
Hiro news & product updates straight to your inbox
Only relevant communications. We promise we won’t spam.

Related stories