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 . This trial will grant you access to our API endpoints and JWT tokens required for authentication.
Table of Contents
Prerequisites
Understanding JWT Tokens
API Configuration
Setting Up Filters, Measures, and Dimensions
Python Implementation
JavaScript Implementation
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 )
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:
Subscribe for a 30-day free trial to get access to Ortege's API or reach out directly to Justin.
After subscribing, you'll receive a JWT token via email.
Keep this token secure; it's your key to access the API.
API Configuration
Below are the API endpoints you'll be interacting with:
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.