Reference

Versioning

Copy page

What we may change without notice, and what ships under a new version path.

The public APIs carry the version in the path, as in /api/v1/.

What can change#

We make additive changes to v1 at any time:

• New optional request fields.
• New response fields.
• New values in the validation.issues[].code list.
• Improved wording in an error message.

Parse responses leniently. Ignore fields you do not recognise. A strict parser that fails on an unknown field will break on a change that breaks nobody else.

What will not change#

Inside v1 we will not:

• Remove or rename a response field.
• Change the type of an existing field.
• Change the meaning of an existing code.
• Make an optional request field required.

Match on code, never on error text. The code is the contract. The message is for a human.

A roster change#

An update that carries no writers used to replace the stored roster, leaving the work with none. It now keeps the stored roster and reports roster_wipe instead.

We changed this because an absent field is not an instruction to erase data. A partner correcting a title should not lose every writer by leaving the field out.

To remove a writer, send the roster that remains.

Enforcement#

We validate what you send. By default we store the works and report the problems, and a 2xx can carry issues. That default does not change, so an integration written before this page did will keep behaving exactly as it does today.

Two things can make us refuse a request instead:

• You ask us to. enforcement: "strict" is a new optional request field. Sending it asks us to return 400 when a blocking issue is present, and to store nothing. This is an additive request field, so it is covered by "What can change" above.
• We agree it with you. We can set your account's default to strict. We will only do that with your written agreement and on a date you choose. We will not change what we accept from a live integration without asking you first.

enforcement: "warn" always overrides an agreed strict default. You can get data in while you fix the cause. The enforcement block on every response names the mode we applied. It also counts the blocking issues your request carried, so you can measure the change before you make it.

We are naming this here because the second case goes further than "What will not change" implies. A strict default does make fields required for you in practice. It is not something you will discover from a 400.

Breaking changes#

Any breaking change ships under a new version path, such as /api/v2/. Version v1 will not change in a way that breaks a working integration.

Machine-readable specs#

The OpenAPI 3.1 spec is the machine-readable contract for the Catalogue Ingest API. Generate a client from it rather than writing request types by hand.