Versioning and governance

What is authoritative

The machine contract of Noryo Merchant API is an OpenAPI 3.1 document. The API reference is generated from it, and the document is not translated: it is one source for everyone, from which a client can generate its code. Guide pages, like this one, explain it and describe the behaviour a schema does not state (idempotency, deduplication, retention).

The version belongs to the family

The version is carried by the path: /merchant/v1. It belongs to the API family, so that a future merchant/v2 can live beside merchant/v1 rather than replace it. The three current routes are all under /merchant/v1.

POST /merchant/v1/enrichments
GET  /merchant/v1/enrichments/{enrichment_id}
POST /merchant/v1/enrichments/{enrichment_id}/refresh

Three numbers, three meanings

The reference shows the publication date; that is what to quote to say "the documentation as I read it". See Changelog.

The host is not part of the contract

Noryo may serve the API from more than one domain. No hostname enters any identity, hash or signature:

• the Location header of a refresh is a relative path;
• a transaction's economic identity does not depend on the host called;
• the type of an error is a link to the documentation, not part of the error code.

The contract currently declares https://api.noryo.app. Put the base URL in your configuration, and do not hardcode it anywhere else.

What is stable, and what is not

The Compatibility page details what your code can rely on (error codes, the format of keys and identifiers) and what may change without a version (the text of error messages, the resolution policy).

In this section

• Compatibility: writing a client that does not break.
• Changelog: the dated publications.