> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/graphprotocol/graph-node/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](https://github.com/graphprotocol/graph-node) - Core indexing protocol
2. [`graph-ts`](https://github.com/graphprotocol/graph-ts) - AssemblyScript runtime library
3. [`graph-cli`](https://github.com/graphprotocol/graph-cli) - Command-line tools
4. `graph-docs` - Documentation site

<Note>
  All steps should be taken **after** relevant `graph-node` changes have been rolled out to production (hosted-service).
</Note>

## 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

<Steps>
  ### Update graph-node Default API Version

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

  <CodeGroup>
    ```rust graph/src/data/subgraph/mod.rs theme={null}
    // 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
    };
    ```
  </CodeGroup>

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

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

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

  ### Create graph-node Release

  1. Update the `graph-node` minor version in `Cargo.toml`
  2. Create a new release with release notes documenting:
     * New API features
     * Breaking changes
     * Migration guide

  ### Update graph-ts

  1. Implement new runtime functions or types corresponding to the API version
  2. Update version in `package.json`
  3. Run tests to ensure compatibility
  4. Create a new release

  <CodeGroup>
    ```json package.json theme={null}
    {
      "name": "@graphprotocol/graph-ts",
      "version": "0.31.0", // Update version
      "description": "TypeScript/AssemblyScript library for writing subgraph mappings"
    }
    ```
  </CodeGroup>

  ### Update graph-cli

  The CLI requires several coordinated updates:

  <Steps>
    #### Write Migrations

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

    <CodeGroup>
      ```typescript migrations/ theme={null}
      // 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;
      }
      ```
    </CodeGroup>

    #### Update Version Restrictions

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

    <CodeGroup>
      ```typescript src/commands/build.ts theme={null}
      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`);
      }
      ```
    </CodeGroup>

    #### Update Package Version

    Update the `graph-cli` version in `package.json`:

    <CodeGroup>
      ```json package.json theme={null}
      {
        "name": "@graphprotocol/graph-cli",
        "version": "0.60.0", // Increment version
        "dependencies": {
          "@graphprotocol/graph-ts": "^0.31.0" // Update graph-ts dependency
        }
      }
      ```
    </CodeGroup>

    #### Update Scaffolded Code

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

    * Scaffold templates
    * Example subgraphs
    * Documentation examples

    <CodeGroup>
      ```yaml subgraph.yaml (template) theme={null}
      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
      ```
    </CodeGroup>

    #### Recompile Examples

    Recompile all example subgraphs:

    ```bash theme={null}
    # Navigate to each example directory
    cd examples/example-subgraph
    npm install
    npm run codegen
    npm run build
    ```

    #### Create CLI Release

    1. Update version and create git tag
    2. Generate release notes
    3. Create GitHub release

    #### Publish to NPM

    ```bash theme={null}
    npm publish
    ```
  </Steps>

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

<CodeGroup>
  ```rust graph/src/data/subgraph/mod.rs theme={null}
  // 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(())
  }
  ```
</CodeGroup>

### Runtime Behavior

Different API versions can have different runtime behavior:

<CodeGroup>
  ```rust runtime/wasm/src/host_exports.rs theme={null}
  // 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();
  }
  ```
</CodeGroup>

## 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

<CodeGroup>
  ```rust runtime/wasm/src/host_exports.rs theme={null}
  // 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)
  }
  ```
</CodeGroup>

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

```bash theme={null}
just test-unit data::subgraph::tests
```

### Integration Tests

Test subgraph deployment with different API versions:

```bash theme={null}
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](/development/chain-integration)
* [Graph Node Architecture](/architecture/overview)
* [Runtime Development](/development/runtime)