Resource filtering pattern
Heimdahl uses a consistent pattern-based filtering approach across all data types, with specific actions for accessing historical data and subscribing to real-time updates. This document explains our filtering pattern syntax, how to use it effectively, and why we chose this approach over alternative filtering methods.
Pattern Structure
Heimdahl provides a consistent pattern structure across interfaces, with slight naming differences between command line and REST API and SDKs.
Command Line Interface
{resource} {action} {pattern}Where:
{resource}is the primary data category (event, transfer, swap) - singular form{action}is eitherlist(for historical data) orsubscribe(for real-time updates){pattern}is a structured filtering expression using dot notation
REST API Interface
/{resources_plural}/{action}/{pattern}Where:
{resources_plural}is the primary data category in plural form (events, transfers, swaps) to follow RESTful conventions{action}is eitherlist(for historical data) orsubscribe(for real-time updates){pattern}is the same structured filtering expression as used in the command line
Actions
Heimdahl provides two primary actions for each resource type:
list: Retrieves historical data matching the specified pattern
subscribe: Creates a real-time subscription for new data matching the pattern
Pattern Syntax By Resource Type
Each resource type has a specific pattern format that reflects its unique properties:
Event Pattern
Examples:
The first query returns historical Transfer events, while the second creates a real-time subscription.
Transfer Pattern
Examples:
The first query returns historical USDC transfers, while the second subscribes to new transfers as they occur.
Swap Pattern
Examples:
The first query returns historical USDC-WETH swaps, while the second creates a real-time subscription.
Using the all Placeholder
all PlaceholderThe keyword all serves as a wildcard for any field you don't want to filter on. This allows for flexible queries that can be refined as needed:
CLI examples:
REST API examples:
Examples
Below are examples showing both CLI and REST API usage for the same queries:
Events for a Specific Contract
CLI:
REST API:
Real-time Transfer Monitoring by Token
CLI:
REST API:
Historical Transfers from a Specific Sender
CLI:
REST API:
Real-time Swap Monitoring Between Specific Token Pairs
CLI:
REST API:
Why Pattern-based Filtering?
Consistency Across Methods
The same pattern structure works for both historical data retrieval and real-time subscriptions, creating a unified query language for all interactions with Heimdahl.
Cross-Chain Scalability
Our pattern approach provides a unified syntax that works across all supported blockchains while respecting their unique characteristics. Adding support for new chains doesn't change the fundamental query structure.
Parameter Extensibility
As we add support for new filtering parameters, the pattern syntax naturally accommodates them in a consistent way. This future-proofs your integration with Heimdahl.
Readability and Brevity
Patterns using dot notation are more concise and readable than traditional query parameters:
CLI:
REST API:
Dotted Pattern vs. Flag-based Filtering
Many blockchain APIs use traditional flag or parameter-based filtering. While familiar, this approach has several disadvantages that our dotted pattern syntax addresses:
Simplicity: Dotted patterns create a natural hierarchy that's easy to understand and remember
Consistency: The same pattern structure works across all data types and interfaces
Brevity: Patterns require significantly fewer characters than equivalent flag-based queries
Extensibility: New filtering parameters can be added without changing the API structure
Readability: Patterns visually represent the relationship between filter parameters
For example, a typical flag-based query might look like:
While our dotted pattern approach simplifies this to:
This approach scales much better as your queries become more complex.
Advanced Usage
Pattern Refinement
Start with broader patterns and refine as needed:
CLI:
REST API:
Implementation Notes
When implementing clients to work with our API, we recommend:
Building pattern-construction utilities to help users create valid patterns
Creating template functions for common queries (list vs. subscribe)
Implementing proper subscription management for real-time data
Conclusion
Our pattern-based filtering approach provides a powerful, consistent, and future-proof way to query blockchain data across different chains and data types. By using the same pattern syntax for both historical (list) and real-time (subscribe) data access, Heimdahl creates a unified experience that simplifies blockchain data integration.
Last updated