Adding a New API Version

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:

graph-node - Core indexing protocol
graph-ts - AssemblyScript runtime library
graph-cli - Command-line tools
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

Update graph-node Default API Version

Update the default value of the GRAPH_MAX_API_VERSION environment variable in graph-node:

graph/src/data/subgraph/mod.rs

// Update the constant to the new API version
pub const GRAPH_MAX_API_VERSION: Version = Version {
    major: 0,
    minor: 0,
    patch: 8, // Increment this value
};

Location: graph/src/data/subgraph/mod.rs

If you’re setting the environment variable manually elsewhere, update or remove those configurations.

The GRAPH_MAX_API_VERSION determines which API features are available to subgraphs. Subgraphs declaring a higher API version than supported will fail validation.

Create graph-node Release

Update the graph-node minor version in Cargo.toml

Create a new release with release notes documenting:

New API features
Breaking changes
Migration guide

Update graph-ts

Implement new runtime functions or types corresponding to the API version

Update version in package.json

Run tests to ensure compatibility

Create a new release

package.json

{
  "name": "@graphprotocol/graph-ts",
  "version": "0.31.0", // Update version
  "description": "TypeScript/AssemblyScript library for writing subgraph mappings"
}

Update graph-cli

The CLI requires several coordinated updates:

Write Migrations

Create migration scripts for the new apiVersion to help developers upgrade their subgraphs:

// Example migration structure
export function migrateToVersion008(manifest: SubgraphManifest): SubgraphManifest {
  // Update apiVersion in manifest
  manifest.specVersion = '1.0.0';
  manifest.dataSources.forEach(ds => {
    ds.mapping.apiVersion = '0.0.8';
  });
  
  // Add any other necessary transformations
  return manifest;
}

Update Version Restrictions

Update version restrictions on build and deploy commands to match the new graph-ts and apiVersion:

const MIN_GRAPH_TS_VERSION = '0.31.0'; // Update to match new graph-ts
const MIN_API_VERSION = '0.0.8'; // Update to new API version

// Validate in command handler
if (!satisfiesVersion(graphTsVersion, MIN_GRAPH_TS_VERSION)) {
  throw new Error(`graph-ts version ${MIN_GRAPH_TS_VERSION} or higher required`);
}

Update Package Version

Update the graph-cli version in package.json:

{
  "name": "@graphprotocol/graph-cli",
  "version": "0.60.0", // Increment version
  "dependencies": {
    "@graphprotocol/graph-ts": "^0.31.0" // Update graph-ts dependency
  }
}

Update Scaffolded Code

Update graph-ts and graph-cli version numbers in:

Scaffold templates
Example subgraphs
Documentation examples

specVersion: 1.0.0
schema:
  file: ./schema.graphql
dataSources:
  - kind: ethereum/contract
    name: Contract
    network: mainnet
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.8  # Update this
      language: wasm/assemblyscript

Recompile Examples

Recompile all example subgraphs:

# Navigate to each example directory
cd examples/example-subgraph
npm install
npm run codegen
npm run build

Create CLI Release

Update version and create git tag
Generate release notes
Create GitHub release

Publish to NPM

npm publish

Update Documentation

Update graph-docs with content about the new apiVersion:

Add migration guide

Document new features

Update API reference

Add code examples

Update version compatibility matrix

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:

// 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:

// 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:

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

// 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:

Document deprecation in release notes
Add warnings when old API versions are used
Provide migration path
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:

Revert the GRAPH_MAX_API_VERSION change
Deploy hotfix to production
Communicate with subgraph developers
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

Contributing

Implementation Details

Extending Graph Node

Adding a New API Version

Overview

Prerequisites

Steps

Write Migrations

Update Version Restrictions

Update Package Version

Update Scaffolded Code

Recompile Examples

Create CLI Release

Publish to NPM

API Version Architecture

How API Versions Work

Version Checking

Runtime Behavior

Extension Points

Adding New Host Functions

Deprecating Features

Testing

Unit Tests

Integration Tests

Compatibility Matrix

Rollback Procedure

Best Practices

Common Issues

Subgraph Fails After Upgrade

Build Failures

Runtime Errors

See Also

Build docs developers (and LLMs) love

Contributing

Implementation Details

Extending Graph Node

​Overview

​Prerequisites

​Steps

​Write Migrations

​Update Version Restrictions

​Update Package Version

​Update Scaffolded Code

​Recompile Examples

​Create CLI Release

​Publish to NPM

​API Version Architecture

​How API Versions Work

​Version Checking

​Runtime Behavior

​Extension Points

​Adding New Host Functions

​Deprecating Features

​Testing

​Unit Tests

​Integration Tests

​Compatibility Matrix

​Rollback Procedure

​Best Practices

​Common Issues

​Subgraph Fails After Upgrade

​Build Failures

​Runtime Errors

​See Also

Build docs developers (and LLMs) love

Overview

Prerequisites

Steps

Write Migrations

Update Version Restrictions

Update Package Version

Update Scaffolded Code

Recompile Examples

Create CLI Release

Publish to NPM

API Version Architecture

How API Versions Work

Version Checking

Runtime Behavior

Extension Points

Adding New Host Functions

Deprecating Features

Testing

Unit Tests

Integration Tests

Compatibility Matrix

Rollback Procedure

Best Practices

Common Issues

Subgraph Fails After Upgrade

Build Failures

Runtime Errors

See Also