Consuming Stacks Stacking data

Introduction

Welcome to this comprehensive guide on how to consume Stacks stacking data using Ortege's REST API powered by Cube. In this tutorial, we'll walk you through the steps to access and manipulate stacking data, set up filters, and utilize measures and dimensions to extract meaningful insights. We'll provide examples in both Python and JavaScript to cater to different preferences.

But first, to fully utilize Ortege's API, we encourage you to subscribe for a 30-day free trial. This trial will grant you access to our API endpoints and JWT tokens required for authentication.

---

Table of Contents

1. Prerequisites

2. Understanding JWT Tokens

3. API Configuration

4. Setting Up Filters, Measures, and Dimensions

5. Python Implementation

6. JavaScript Implementation

7. Conclusion

---

Prerequisites

• Basic understanding of RESTful APIs

• Familiarity with JSON

• Python 3.6+ or Node.js installed on your machine

• Access to Ortege's API (Get your JWT token by subscribing to our 30-day free trial)

---

Understanding JWT Tokens

JSON Web Tokens (JWT) are an open, industry-standard method for representing claims securely between two parties. In our case, the JWT token is used for authenticating requests to Ortege's API endpoints.

How to Obtain a JWT Token:

1. Subscribe for a 30-day free trial to get access to Ortege's API or reach out directly to Justin.

2. After subscribing, you'll receive a JWT token via email.

3. Keep this token secure; it's your key to access the API.

---

API Configuration

Below are the API endpoints you'll be interacting with:

REST_LOAD_URL = "https://api-staging.ortege.ai/cubejs-api/v1/load/"
SQL_URL = "https://api-staging.ortege.ai/cubejs-api/v1/sql/"
GRAPHQL_URL = "https://api-staging.ortege.ai/cubejs-api/graphql"
WEBSOCKET_URL = "wss://api-staging.ortege.ai/cubejs-api/v1/load/"

---

Setting Up Filters, Measures, and Dimensions

Measures are quantitative values you want to analyze, like sums or counts.

• Example: stacks_stacked_stx.stacked_amount - The total amount stacked.

Dimensions are attributes or categorical values used to segment your data.

• Example:

  • stacks_stacked_stx.cycle - The cycle number.

  • stacks_stacked_stx.pox_version - The version of Proof of Transfer.

  • stacks_stacked_stx.stacking_tx_type - The type of stacking transaction. These can be either:

    • stack-extend

    • delegate-stack-stx

    • stack-stx

    • stack-increase

Filters are conditions used to limit the data returned by the query.

• Example: Only include cycles from 80 onwards.

---

Python Implementation

Installation

Install the required Python packages:

pip install requests

Code Example

import requests
import json

# Configuration Parameters
REST_LOAD_URL = "https://api-staging.ortege.ai/cubejs-api/v1/load/"
jwt_token = "YOUR_JWT_TOKEN"  # Replace with your actual JWT token

# Define the headers, including the Authorization header with JWT token
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {jwt_token}"
}

def rest_api_query(query_payload):
    """
    Executes a REST API query against Cube.js.
    """
    response = requests.post(REST_LOAD_URL, headers=headers, json=query_payload)
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"REST API query failed: {response.status_code} - {response.text}")

def example_rest_query():
    """
    REST API query: Sum of stacks_stacked_stx.stacked_amount
    Grouped by cycle, pox_version, and stacking_tx_type.
    Includes a filter to only include cycles from 80 onwards.
    """
    query_payload = {
        "query": {
            "measures": ["stacks_stacked_stx.stacked_amount"],
            "timeDimensions": [],
            "dimensions": [
                "stacks_stacked_stx.cycle",
                "stacks_stacked_stx.pox_version",
                "stacks_stacked_stx.stacking_tx_type"
            ],
            "filters": [
                {
                    "dimension": "stacks_stacked_stx.cycle",
                    "operator": "gte",
                    "values": ["80"]
                }
            ]
        }
    }
    return query_payload

def main():
    try:
        # Use the basic query with cycle filter
        rest_query = example_rest_query()

        rest_result = rest_api_query(rest_query)
        print("\n--- REST API Query Result ---")
        print(json.dumps(rest_result, indent=2))
    except Exception as e:
        print(f"REST API Error: {str(e)}")

if __name__ == "__main__":
    main()

Explanation

• Headers: Include your JWT token in the Authorization header.

• Query Payload: Define your measures, dimensions, and filters.

• Executing the Query: Use the requests library to send a POST request to the REST API endpoint.

---

JavaScript Implementation

Installation

Install the required Node.js packages:

npm install axios

Code Example

const axios = require('axios');

// Configuration Parameters
const REST_LOAD_URL = "https://api-staging.ortege.ai/cubejs-api/v1/load/";
const jwt_token = "YOUR_JWT_TOKEN"; // Replace with your actual JWT token

// Define the headers, including the Authorization header with JWT token
const headers = {
  "Content-Type": "application/json",
  "Authorization": `Bearer ${jwt_token}`
};

async function restApiQuery(queryPayload) {
  try {
    const response = await axios.post(REST_LOAD_URL, queryPayload, { headers });
    console.log("\n--- REST API Query Result ---");
    console.log(JSON.stringify(response.data, null, 2));
  } catch (error) {
    console.error(`REST API Error: ${error.response.status} - ${error.response.statusText}`);
  }
}

function exampleRestQuery() {
  return {
    "query": {
      "measures": ["stacks_stacked_stx.stacked_amount"],
      "timeDimensions": [],
      "dimensions": [
        "stacks_stacked_stx.cycle",
        "stacks_stacked_stx.pox_version",
        "stacks_stacked_stx.stacking_tx_type"
      ],
      "filters": [
        {
          "dimension": "stacks_stacked_stx.cycle",
          "operator": "gte",
          "values": ["80"]
        }
      ]
    }
  };
}

(async function main() {
  const restQuery = exampleRestQuery();
  await restApiQuery(restQuery);
})();

Explanation

• Headers: JWT token is included in the Authorization header.

• Async/Await: Using asynchronous functions to handle the API request.

• Axios Library: Simplifies HTTP requests in Node.js.

---

Conclusion

You've now learned how to consume Stacks stacking data using Ortege's REST API in both Python and JavaScript. By setting up measures, dimensions, and filters, you can customize your queries to extract the data most relevant to your needs.