API Versioning Strategy

The 1990 Web Archive API uses a multi-strategy versioning system designed to maintain backward compatibility while supporting evolving archival standards, rendering engines, and data schemas. This document outlines how versions are identified, how deprecations are communicated, and how to migrate between versions.

ℹ️ Versioning Philosophy

We prioritize predictable, long-lived versions. Breaking changes are only introduced in new major versions, and we maintain a minimum 12-month overlap between adjacent versions.

Supported Versioning Strategies

The API supports three standard versioning mechanisms. Clients may use any combination, with precedence applied in the order listed below:

                    Precedence Order
                    HTTP
                
1. Path Parameter (Highest Priority)
GET /api/v2/archive/search?q=geocities

2. Accept Header
Accept: application/vnd.1990archive.v1+json

3. Query Parameter
GET /api/archive/search?api_version=v1&q=angelfire

Path Versioning

Recommended for most integrations. Explicitly includes the version in the URL path, making it visible in logs, proxies, and browser developer tools.

Content Negotiation (Headers)

Uses standard HTTP `Accept` headers for version negotiation. Ideal for SDKs and clients that prefer clean URLs and strict HTTP semantics.

Query Parameter Versioning

Fallback method for legacy systems or rapid prototyping. Less recommended for production due to URL fragmentation and caching complications.

Current API Versions

Version	Status	Release Date	Sunset Date	Description
`v3`	Beta	2024-11-01	—	GraphQL support, advanced rendering pipelines, real-time crawl status
`v2`	Stable	2023-03-15	2026-03-15	Modern REST, JSON:API compliant, paginated responses, filter/query DSL
`v1`	Deprecated	2020-08-22	2025-08-22	Legacy REST, XML/JSON toggle, basic pagination, Netscape-era field names
`v0`	Sunset	2018-01-10	2024-01-10	Initial public release, raw HTML dumping, limited rate limits

Deprecation & Sunset Policy

We follow a strict communication protocol for version lifecycles to ensure smooth transitions:

Deprecation Notice: Published 12 months before sunset. Returns Deprecation and Sunset headers.
Migration Guide: Detailed field mappings, breaking changes, and code examples provided alongside the notice.
Read-Only Mode: Activated 30 days before sunset. Write/modify endpoints return 403.
Sunset: Endpoint returns 410 Gone with a permanent redirect to the migration docs.

                    Deprecation Headers
                    HTTP Response
                
Deprecation: Sat, 22 Aug 2025 00:00:00 GMT
Sunset: Sat, 22 Aug 2025 00:00:00 GMT
Link: <https://docs.1990archive.com/migrate/v1-to-v2>; rel="successor-version"
Warning: 299 - "API v1 is deprecated. Please migrate to v2"

Request Examples

Path Versioning (Recommended)

                    cURL
                    bash
                
curl -X GET https://api.1990archive.com/v2/archive/render \\
  -H "Authorization: Bearer <your_token>" \\
  -H "Content-Type: application/json" \\
  -d '{
    "url": "http://www.geocities.com/SunsetStrip/5432",
    "timestamp": "1998-11-04T14:30:00Z",
    "format": "html"
  }'

Header Negotiation

                    cURL
                    bash
                
curl -X GET https://api.1990archive.com/archive/search \\
  -H "Accept: application/vnd.1990archive.v2+json" \\
  -H "Authorization: Bearer <your_token>" \\
  -d '{
    "query": "under construction gif",
    "era": "1995-1999",
    "page": 1
  }'

Standard Response Headers

Every API response includes versioning and compliance headers regardless of the negotiation method used:

                    Response Headers
                    HTTP
                
X-API-Version: v2
X-Request-Id: req_8a7b3c9d2e1f
RateLimit-Remaining: 842
RateLimit-Reset: 1718992800
Cache-Control: public, max-age=3600, s-maxage=7200
Content-Type: application/json; charset=utf-8

Migration Guide Highlights

⚠️ Critical Changes in v1 → v2

Field naming conventions changed from snake_case to kebab-case for URLs and camelCase for JSON payloads. Pagination switched from offset-based to cursor-based. Response envelope now uses data, meta, and links keys per JSON:API spec.

Field Mapping Example

                    v1 vs v2 Payload
                    json
                
/* v1 Legacy Structure */
{
  "archive_id": "arc_990112",
  "snap_date": "1999-12-31",
  "raw_html": "<html>...</html>",
  "next_offset": 50
}

                    v2 Modern Structure
                    json
                
{
  "data": {
    "id": "arc_990112",
    "snapshot-date": "1999-12-31T00:00:00Z",
    "content": {
      "html": "<html>...</html>"
    }
  },
  "meta": { "version": "v2" },
  "links": {
    "next": "https://api.1990archive.com/v2/archive/search?cursor=eyJpZCI6IjUwIn0"
  }
}

Need help migrating? Check our full changelog or reach out to developer support.