API Versioning

The Glyph API uses versioning to ensure stability while enabling continuous improvement. This guide explains our versioning strategy and commitment to backwards compatibility.

Current Version

The current Glyph API version is v1. All endpoints are prefixed with /v1/.

https://api.glyph.you/v1/preview
https://api.glyph.you/v1/modify
https://api.glyph.you/v1/generate
https://api.glyph.you/v1/create

Versioning Strategy

Glyph uses URL-based versioning with the version number as the first path segment after the base URL:

https://api.glyph.you/{version}/{endpoint}

This approach provides:

• Explicit version selection - You always know which version you’re using
• Easy migration - Switch versions by changing the URL prefix
• Parallel operation - Multiple versions can run simultaneously during transitions
• Clear deprecation path - Old versions remain accessible during sunset periods

Why URL Versioning?

We chose URL-based versioning over header-based versioning because:

1. Visibility - The version is visible in logs, documentation, and debugging
2. Caching - CDNs and proxies can cache different versions independently
3. Simplicity - No special headers required; works with any HTTP client
4. Testing - Easy to test different versions in a browser or curl

Checking API Version

Health Endpoint

Check the current API version using the health endpoint:

curl https://api.glyph.you/health

Response:

{
  "status": "ok",
  "version": "0.28.6",
  "timestamp": "2025-01-15T12:00:00.000Z"
}

Note

The version field in the health response refers to the implementation version (software release), not the API version. The API version (v1) is stable and separate from implementation updates.

Response Headers

Every API response includes version information in headers:

Header	Description
X-Glyph-Version	Current API version (e.g., v1)
X-Request-Id	Unique request identifier for debugging

Backwards Compatibility

Our Commitment

For any given API version, we guarantee:

• Existing endpoints will not be removed within that version
• Existing response fields will not be removed or change type
• Existing request parameters will continue to work as documented
• Error codes and formats will remain consistent

What We May Change

Within a version, we may:

• Add new optional fields to responses
• Add new optional parameters to requests
• Add new endpoints
• Add new error codes for new scenarios
• Improve performance and reliability

Tip

Always handle unknown fields gracefully in your code. New fields may be added to responses at any time without a version bump.

Example: Safe Response Handling

// Good: Safely access fields, handle new ones gracefully
const response = await fetch('https://api.glyph.you/v1/preview', {...});
const data = await response.json();

const html = data.html;
const sessionId = data.sessionId;
// New fields won't break this code

# Good: Use .get() for safe access
response = requests.post('https://api.glyph.you/v1/preview', ...)
data = response.json()

html = data.get('html')
session_id = data.get('sessionId')
# New fields won't break this code

Deprecation Policy

When we need to introduce breaking changes, we follow a structured deprecation process:

Timeline

Phase	Duration	Actions
Announcement	Day 0	New version released, deprecation notice published
Migration Period	6 months	Both versions operate, migration guides available
Sunset Warning	3 months before	Email notifications, dashboard warnings
End of Life	After 6 months	Old version returns 410 Gone

How We Communicate

1. Email notifications to all API key holders
2. Dashboard banners in your Glyph dashboard
3. Documentation updates with migration guides
4. Deprecation headers in API responses

Deprecation Headers

When using a deprecated version or endpoint, responses include:

Sunset: Sat, 01 Jan 2026 00:00:00 GMT
Deprecation: true
Link: <https://docs.glyph.you/api/versioning>; rel="deprecation"

Migration Between Versions

Best Practices

1. Test in staging first - Use a separate API key for testing
2. Update incrementally - Migrate one endpoint at a time
3. Monitor for errors - Watch for unexpected behavior after migration
4. Keep rollback ready - Maintain ability to switch back temporarily

Version Coexistence

During migration periods, you can use multiple versions:

// Old integration (still works during migration)
const legacyUrl = 'https://api.glyph.you/v1/preview';

// New integration
const newUrl = 'https://api.glyph.you/v2/preview';

// Gradually migrate traffic
const url = useNewVersion ? newUrl : legacyUrl;

Breaking Changes

A breaking change requires a new API version. Examples include:

Change Type	Example	Breaking?
Remove endpoint	Delete /v1/analyze	Yes
Remove response field	Remove html from preview response	Yes
Change field type	Change total from number to string	Yes
Rename parameter	Rename template to templateId	Yes
Add required parameter	New required format field	Yes
Add optional field	Add metadata to response	No
Add new endpoint	Add /v1/batch/status	No
Improve error messages	Better validation errors	No

Self-Hosted Deployments

For self-hosted Glyph deployments:

• You control your own versioning and upgrade schedule
• The same API version guarantees apply
• Check release notes before upgrading

# Check your deployment version
curl https://your-glyph-instance.com/health

Need Help?

• Migration questions: hello@glyph.you
• Enterprise support: Contact your account manager
• Documentation issues: Open a GitHub issue