API Versioning
SDD Classification: L3-Technical
Authority: Engineering Team
Review Cycle: Quarterly
Versioning Strategy
Materi uses URL-based versioning with a commitment to backward compatibility:
https://api.materi.dev/v1/documents
https://api.materi.dev/v2/documents (future)
Current Version
| Property | Value |
|---|
| Current Version | v1 |
| Status | Stable |
| Base URL | https://api.materi.dev/v1 |
| Released | 2024-Q3 |
Version in Request
URL Path (Required)
GET https://api.materi.dev/v1/documents
POST https://api.materi.dev/v1/documents
Accept: application/vnd.materi.v1+json
Accept: application/vnd.materi.v1.1+json
Backward Compatibility
What We Consider Backward Compatible
These changes are made without version bumps:
| Change Type | Example |
|---|
| Adding new endpoints | POST /api/v1/templates |
| Adding optional fields | New metadata field in response |
| Adding new enum values | New status: "archived" option |
| Relaxing validation | Increasing max title length |
| Adding new query parameters | ?include_deleted=true |
| New response headers | X-Request-Duration |
What Requires New Version
These changes require a new API version:
| Change Type | Example |
|---|
| Removing endpoints | Removing DELETE /users |
| Removing fields | Removing legacy_id from response |
| Changing field types | id from integer to string |
| Renaming fields | user_id to owner_id |
| Changing validation | Stricter email validation |
| Changing default behavior | Different default sort order |
Deprecation Policy
Timeline
| Phase | Duration | Actions |
|---|
| Announcement | Day 0 | Changelog, email, docs update |
| Migration Period | 12 months | Both versions supported |
| Sunset Warning | 6 months | Deprecation headers, warnings |
| End of Life | After 18 months | Old version returns 410 Gone |
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jul 2026 00:00:00 GMT
Link: <https://docs.materi.dev/migration/v1-to-v2>; rel="deprecation"
Version Migration
Checking Your Version
Response:
{
"version": "v1",
"build": "2025.01.07.1234",
"deprecation": {
"is_deprecated": false,
"sunset_date": null,
"migration_guide": null
}
}
Feature Flags
Request specific features within a version:
X-Materi-Features: new-editor,beta-ai
SDK Version Compatibility
| SDK | API v1 Support | Notes |
|---|
| JavaScript 1.x | ✅ | Current |
| JavaScript 2.x | ✅ | Current |
| Python 1.x | ✅ | Current |
| Go 1.x | ✅ | Current |
Changelog
v1.1 (2025-01-07)
Added:
POST /ai/analyze - Document analysis endpointmetadata field on document responsesinclude_deleted query parameter
Changed:
- Increased rate limits for Professional tier
v1.0 (2024-09-15)
Initial Release:
- Document CRUD operations
- Workspace management
- User authentication
- AI content generation
- Real-time collaboration
Migration Guides
When a new version is released, migration guides will be available:
API Status
Health Endpoints
# API health check
GET /health
# API readiness (includes dependencies)
GET /ready
# API version info
GET /api/v1/version
Status Page
Monitor API status and planned maintenance:
Best Practices
For API Consumers
- Pin to a specific version in production
- Subscribe to changelog for updates
- Test against staging before production
- Handle deprecation headers in your code
- Plan migrations early during migration period
Version Detection
class MateriClient {
constructor(config) {
this.version = config.apiVersion || 'v1';
this.baseUrl = `https://api.materi.dev/${this.version}`;
}
async checkDeprecation(response) {
if (response.headers.get('Deprecation') === 'true') {
const sunset = response.headers.get('Sunset');
const guide = response.headers.get('Link');
console.warn(`API version deprecated. Sunset: ${sunset}`);
console.warn(`Migration guide: ${guide}`);
}
}
}
Document Status: Complete
Version: 2.0
