Versioning

This page explains how the Wingspan V3 API is versioned and what that means for your client. The short version: the /v3/ in every path is the major version, and you don't need to send anything else today.

The major version is in the URL

Every path starts with /v3/. V1 endpoints (/payments/collaborator, /payments/payable, and so on) are a separate API. See Migrating from V1.

The Wingspan-Version header

The API reads a Wingspan-Version request header. Today it accepts one value, default, and responses echo the version that produced them:

HTTP/1.1 200 OK
Wingspan-Version: default

Omit the header or send Wingspan-Version: default. A request without it is handled as default. Sending any other value, such as a date, returns 422 ValidationError with an UnsupportedValue error on Wingspan-Version. Dated versions aren't available yet. Responses echo Wingspan-Version: default.

The version is part of the idempotency fingerprint. If you retry with the same Idempotency-Key but a different Wingspan-Version, you get 409 IdempotencyKeyConflict.

The version of a webhook event's payload is set when the event is created and is carried in the event's apiVersion field. It doesn't follow the Wingspan-Version of your requests. See Webhooks and events.

Write a client that handles additions

Wingspan adds to the V3 API over time: new endpoints, new optional fields, new values in open-ended lists. Build your client so these additions don't break it:

• Ignore response fields you don't recognize. Don't fail when a response has a field your code doesn't know about.
• Don't send fields you haven't read about. Some endpoints reject an unknown field with 422, and others ignore it, so check field names against the reference. See Request and response conventions.
• Handle unknown values in open-ended lists. operationType on async operations, detailCode on errors, and webhook event type values grow over time. Keep a default branch for values you don't recognize.
• Branch on code in errors, not on detail text or detailCode. See Errors.
• Treat IDs and page tokens as opaque strings. Don't parse them or depend on their length beyond what the conventions state.

Related pages

• Request and response conventions
• Errors
• Migrating from V1