Versioning and Deprecation

Some of the API is a contract: you can build a site or an app on it and it will keep working. This page says which operations those are, what we may change without telling you, and how much warning you get before a breaking change.

The stable operations

The stable operations are published as one file, the public API contract:

https://docs.chaindaddy.io/openapi-public.yaml

It is an OpenAPI 3.0 document with only the stable operations and the schemas they use. Today it covers:

Group	What it is for
Public reads	A verified coin, the apps on its page, a wallet's holding and a coin's verified sites, with no key
Sign in with Chain Daddy	Discovery, the signing keys, the token endpoint, the profile and sign-out
A store run with a store key	Items, orders, what a wallet owns, drops, prizes, messages, events and receipt checks
Webhooks	Your webhooks and a store's own purchase webhook

The API Explorer and the full spec list every endpoint. An endpoint that is in the full spec and not in the contract follows the product: it can change when the feature it serves changes.

What a stable operation promises

A stable operation is kept for at least 12 months after we announce that it is going away. During those months it keeps answering as the contract says.

A breaking change is one that can stop working code from working:

• an operation, a parameter, a success response or a field in it is removed;
• a field changes type;
• a parameter or a request field becomes required;
• a value you could send is no longer accepted;
• a response field that was always present can now be missing.

Every change to the contract is checked against this list before it ships.

One exception: we may change or turn off an operation sooner when leaving it as it is would put people's funds or data at risk, or when the law requires it. We say so in What's New when that happens.

What can change without notice

These are not breaking changes, and they happen often. Write your code to expect them:

• a new operation;
• a new optional parameter or request field;
• a new field in a response. Ignore fields you do not know.
• a new value in a list of values a response can carry, such as a new order status. Handle a value you have not seen.
• a new error response, or new wording in an error's message. Read an error's code, never its message.
• a different rate limit. Read Retry-After on a 429.

How you are told

When a stable operation is deprecated:

1. Every answer from it carries two headers: Deprecation: true, and Sunset with the date after which it may stop answering, for example Sunset: Mon, 11 Oct 2027 00:00:00 GMT.
2. The contract marks the operation deprecated: true and its description names what replaces it.
3. What's New lists it, with the replacement and the date.

After the Sunset date the operation may answer 404 or 410.

To catch a deprecation without reading this site, log any response that has a Deprecation header.

Versions in the path

The path carries the major version: /api/v2/…. A redesign that cannot be made compatible gets a new path, and the old one follows the rules above.

Types for TypeScript

The contract is also published as TypeScript types in @chaindaddy/js:

import type { paths, components } from '@chaindaddy/js/api';

type Order = components['schemas']['IapOrder'];

They are types only. Call the API with fetch or any HTTP client.