API methodology

Every conversion Convertitive ships is also a JSON endpoint under /api/v1/. The API has been live since FAZ 4 and serves the same factors and formulas as the UI — if a result is correct on the page, it’s correct from the API.

Endpoint design

REST-style. Path describes the resource, query string carries the parameters. Examples:

• GET /api/v1/convert/unit?category=length&from=cm&to=inches&value=5
• GET /api/v1/convert/currency?from=USD&to=EUR&value=100
• GET /api/v1/convert/color?from=hex&to=rgb&value=%23FF6B35
• GET /api/v1/categories — list every unit category
• GET /api/v1/health/ — service health (uptime + version)

No POST bodies. All inputs are query parameters. Idempotent, cacheable, browser-friendly.

Response envelope

Every successful response uses the same shape:

{
  "ok": true,
  "data": { /* endpoint-specific */ },
  "meta": { /* optional metadata: rateDate, factor, etc. */ }
}

Every error response:

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAM",
    "message": "Human-readable explanation",
    "param": "from"
  }
}

Standard HTTP status codes: 200 for success, 400 for input errors, 404 for unknown categories/units, 500 only when something genuinely broke. Don’t treat 4xx as retryable.

CORS policy

Access-Control-Allow-Origin: * on every API endpoint. Use it from any origin, including localhost development. No preflight needed because every request is GET with no custom headers — simple-request rules apply.

No authentication

No API key, no OAuth, no signed requests. Every endpoint is anonymous. Three reasons:

1. The data isn’t valuable enough to gate. Unit conversion factors are public-domain. ECB rates are publicly republished by ~20 services. Charging for them would be charging for someone else’s data.
2. Auth adds friction for the dominant use case. A developer testing a feature, a student scripting a homework comparison, a hobbyist building a tracker — none of them want to register first.
3. Rate limits handle abuse.Cloudflare’s defaults plus the trivial computational cost of each conversion mean someone trying to scrape Convertitive can get the data faster by mirroring the public ECB feed directly.

Versioning

The /api/v1/ prefix is intentional. When the response envelope or error shape changes meaningfully, a/api/v2/ships alongside; v1 is supported for at least 12 months past v2’s launch.

Bug-fix and additive changes (new endpoints, new optional fields in responses) ship continuously without a version bump.

Currency rate freshness

Currency endpoints return the ECB mid-market rate cached for one hour via ISR. The meta.rateDate field in every currency response tells you when the rate was published (always a recent ECB business day). For high- precision real-time work, get rates from your broker; for anything else, our cache is fine.

What we won’t add to the API

• POST endpoints for stateful operations (we have no state).
• Bulk endpoints (loop over the singletons; it’s fast enough).
• WebSocket / streaming (the data doesn’t change frequently enough to justify the protocol).
• API keys / paid tiers (see “no authentication” above).

Live docs at /api/.