Skip to content

Versioning

What may change within v1, and what never does.

Updated

Every path starts with /v1. Within /v1, the API only grows: code written against it today keeps working.

What may change within v1

  • New operations, and new events for webhooks.
  • New optional arguments on an operation.
  • New fields in an answer, at any depth, and in a webhook’s data.
  • New values of an enum: in an argument, and in an answer.
  • New filters, sorts, search fields and facets on a list.
  • Wording: a problem’s title and detail, an operation’s summary.

So read answers tolerantly: ignore fields you don’t know, treat an enum value you don’t know as “other” rather than an error, and branch on a problem’s type or code, never its sentences. The OpenAPI document marks enums that may grow in answers with x-extensible-enum.

What never changes within v1

  • An operation’s path, method or scope.
  • An argument’s name or type, or its limits narrowed; an optional argument turned required; an argument value refused that was taken.
  • A field removed from an answer, renamed, given another type, or made optional or nullable.
  • A list’s sort removed or renamed, or where its rows with no value fall.
  • A write that takes an Idempotency-Key stopping to take one.

A change of that kind ships as a new operation beside the old one, which keeps working. Every change to the API is checked against this list before it ships.

Following changes

The reference and the OpenAPI document at https://api.sherpo.io/merchant/openapi.json are rebuilt from the API itself on every release, so they always describe what runs.

Type to search…

↑↓ navigate↵ selectEsc close