Adding a New API Version

Guide for coordinating apiVersion upgrades across Graph Protocol projects

This guide explains how to coordinate an apiVersion upgrade across all impacted Graph Protocol projects. API versions control the features and behaviors available to subgraph developers.

Overview

An API version upgrade affects multiple repositories in the Graph Protocol ecosystem:

1. graph-node - Core indexing protocol
2. graph-ts - AssemblyScript runtime library
3. graph-cli - Command-line tools
4. graph-docs - Documentation site

All steps should be taken after relevant graph-node changes have been rolled out to production (hosted-service).

Prerequisites

• All new features and breaking changes must be implemented in graph-node
• Changes must be deployed and stable in production
• Test coverage for new features must be in place

Steps

API Version Architecture

How API Versions Work

API versions in Graph Node use semantic versioning and control:

• Available host functions in the WASM runtime
• Data types and interfaces
• Query capabilities
• Validation rules

Version Checking

The version check happens during subgraph deployment:

graph/src/data/subgraph/mod.rs

// Simplified version check logic
pub fn validate_api_version(requested: &Version) -> Result<(), Error> {
    let max_version = GRAPH_MAX_API_VERSION;
    
    if requested > &max_version {
        return Err(anyhow!(
            "subgraph requires API version {}, but only {} is supported",
            requested,
            max_version
        ));
    }
    
    Ok(())
}

Runtime Behavior

Different API versions can have different runtime behavior:

runtime/wasm/src/host_exports.rs

// Example: Feature gated by API version
if mapping_api_version >= Version::new(0, 0, 8) {
    // Enable new feature
    enable_advanced_indexing();
} else {
    // Use legacy behavior
    use_legacy_indexing();
}

Extension Points

Adding New Host Functions

When adding host functions that require a new API version:

1. Implement in graph-node: Add the function to the runtime host exports
2. Update graph-ts: Add TypeScript/AssemblyScript bindings
3. Gate by version: Check API version before allowing usage

runtime/wasm/src/host_exports.rs

// Add new host function
pub fn ethereum_call_advanced(
    &mut self,
    contract_address: Vec<u8>,
    function: String,
    args: Vec<Token>,
) -> Result<Vec<Token>, Error> {
    // Verify API version
    if self.api_version < Version::new(0, 0, 8) {
        return Err(anyhow!("ethereum.callAdvanced requires API version 0.0.8"));
    }
    
    // Implementation
    self.eth_adapter.call_advanced(contract_address, function, args)
}

Deprecating Features

To deprecate features:

1. Document deprecation in release notes
2. Add warnings when old API versions are used
3. Provide migration path
4. Remove after sufficient grace period

Testing

Unit Tests

Test API version validation:

just test-unit data::subgraph::tests

Integration Tests

Test subgraph deployment with different API versions:

TEST_CASE=api_version just test-integration

Compatibility Matrix

Maintain a compatibility matrix:

graph-node	graph-ts	graph-cli	API Version
0.34.0	0.31.0	0.60.0	0.0.8
0.33.0	0.30.0	0.59.0	0.0.7

Rollback Procedure

If issues are discovered:

1. Revert the GRAPH_MAX_API_VERSION change
2. Deploy hotfix to production
3. Communicate with subgraph developers
4. Address issues before re-attempting upgrade

Best Practices

• Backward Compatibility: Maintain compatibility with older API versions when possible
• Gradual Rollout: Test in staging before production
• Clear Documentation: Provide detailed migration guides
• Version Pinning: Allow users to pin to specific versions
• Breaking Changes: Minimize breaking changes between versions

Common Issues

Subgraph Fails After Upgrade

Symptom: Subgraph stops syncing after API version upgrade

Solution: Check compatibility, review breaking changes, update mapping code

Build Failures

Symptom: graph build fails with version mismatch

Solution: Ensure graph-ts and graph-cli versions are compatible

Runtime Errors

Symptom: “Function not found” errors in subgraph logs

Solution: Verify API version supports the called functions

See Also

• Chain Integration Guide
• Graph Node Architecture
• Runtime Development