API Versioning Guide

The Firma API uses header-based versioning via the X-API-Version header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

How to Specify a Version

Include the X-API-Version header in your request:

curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);

import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)

If the X-API-Version header is omitted, the API defaults to the current stable version (currently 1).

Version Lifecycle

Each API version goes through three stages:

Status	Description	Behavior
active	Fully supported version	Normal responses with `X-API-Version` header
deprecated	Still functional but scheduled for removal	Responses include deprecation warning headers
sunset	Removed from service	Returns `410 Gone` error

Response Headers

For Active Versions

X-API-Version: 1

For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.

Header	Description
`Deprecation`	RFC 8594 compliant - Date when the version was deprecated
`Sunset`	RFC 8594 compliant - Date when the version will be removed
`X-Deprecated-Message`	Human-readable warning message

Error Responses

Invalid Version Header

// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}

Unsupported Version

// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}

Sunset Version (Removed)

// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}

Breaking Changes Policy

Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

The previous version is marked as deprecated
You’ll receive warning headers for a recommended 6-month deprecation period
After the sunset date, the old version returns 410 Gone

What Constitutes a Breaking Change?

Breaking changes include:

Removing or renaming existing fields
Changing field types or validation rules
Removing endpoints
Changing authentication requirements
Modifying rate limits significantly

Non-breaking changes include:

Adding new optional fields
Adding new endpoints
Adding new enum values (if your client handles unknown values gracefully)
Improving error messages

Best Practices

Always check for deprecation headers

Implement automated checks in your API client code to detect Deprecation and Sunset headers. Log warnings when these headers are present.

const response = await fetch(url, options);

if (response.headers.get('Deprecation')) {
  console.warn('API Deprecation Warning:', {
    deprecation: response.headers.get('Deprecation'),
    sunset: response.headers.get('Sunset'),
    message: response.headers.get('X-Deprecated-Message')
  });
}

Explicitly specify the version

Rather than relying on the default version, always specify the X-API-Version header explicitly. This prevents unexpected breaking changes when the default version changes.

// Good - explicit version
headers: { 'X-API-Version': '1' }

// Avoid - relies on default
headers: { }

Test against new versions early

When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:

Identify breaking changes in your implementation
Update your code and dependencies
Test thoroughly in staging
Deploy with confidence before the deadline

Current Version Status

The current active version is v1 with no deprecation scheduled at this time.

When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

Authentication

Learn about API key authentication and JWT tokens

Complete Setup Guide

Get started with the Firma API

Webhooks

Set up webhook notifications for events

API Reference

Browse all API endpoints

​API Versioning Guide

​How to Specify a Version

​Version Lifecycle

​Response Headers

​For Active Versions

​For Deprecated Versions

​Error Responses

​Invalid Version Header

​Unsupported Version

​Sunset Version (Removed)

​Breaking Changes Policy

​What Constitutes a Breaking Change?

​Best Practices

​Current Version Status

​Related Resources

Authentication

Complete Setup Guide

Webhooks

API Reference

API Versioning Guide

How to Specify a Version

Version Lifecycle

Response Headers

For Active Versions

For Deprecated Versions

Error Responses

Invalid Version Header

Unsupported Version

Sunset Version (Removed)

Breaking Changes Policy

What Constitutes a Breaking Change?

Best Practices

Current Version Status

Related Resources