Versioning

PaxFaB Servicing is a versioned API. This allows Paxport to safely deliver new features and fixes.

API versions are identified with a Major and a Minor number - Major.Minor (e.g 1.1).

For the API endpoints served by Paxport the major version is included in the API URL path (e.g /v1/).

Minor

When a new minor version is released Paxport will seamlessly migrate you between minor versions of the same major version.

No development work should be required when migrating between minor versions of the same major version as long as your initial integration adheres to Paxport’s guidance. Though you may wish to make changes to take advantage of the new features included in the minor upgrade.

Major

Major version releases will almost certainly require you to make development changes. Following any changes you will then need to:

• Adjust your requests to use the new major version URL
• Or in the case of webhooks, provide Paxport with your latest URL

Major versions are supported for a fixed period of time from the end of life announcement date. Support periods are as follows:

• Generally available API endpoint - 6 months
• Beta API endpoint - 1 month
• Alpha API endpoint - 1 week

Once a major version has reached its end of life date it will no longer be usable.

All endpoints on the production domain (https://paxfab.paxportapis.com) can be considered Generally Available unless otherwise stated (see below exemption list).

Notifications

Emails will be sent out for all release events. It is therefore important that you keep your release contacts up to date with Paxport Customer Services.

Change definition

For APIs where you are the caller/client and Paxport is the server we consider the following Paxport initiated changes to be minor:

• Adding new API endpoints/messages
  • As long as they don’t result in a mandatory change to an existing flow.
• Adding new values to an enum
• API Request:
  • Adding new optional request fields
  • Making a mandatory request field optional
  • Loosening a request field’s validation, e.g accepting longer strings
• API Response:
  • Adding new response fields
  • Making an optional response field mandatory
  • Removing an optional response field
  • Reordering of response fields for JSON objects
  • Tightening a response field’s validation
  • Changing the contents of any response field as long as its type does not change
    • E.g the contents of fields only specified as “string” frequently change. These are commonly used for IDs and Descriptions

For APIs where Paxport is the caller/client and you are the server (e.g webhooks) we consider the following Paxport initiated changes to be minor:

• Adding new API messages
  • As long as they don’t result in a mandatory change to an existing flow.
  • And as long as they don’t result in Paxport sending the new messages to you without prior agreement
• Adding new values to an enum
• API Request:
  • Adding new request fields
  • Making an optional request field mandatory
  • Removing an optional request field
  • Reordering of request fields for JSON objects
  • Tightening a request field’s validation
  • Changing the contents of any request field as long as its type does not change
    • E.g the contents of fields only specified as “string” frequently change. These are commonly used for IDs and Descriptions
• API Response:
  • Adding new optional response fields
  • Making a mandatory response field optional
  • Loosening a response field’s validation, e.g accepting longer strings

Exemptions

Certain endpoints/messages may be wholly or partially exempt from the versioning policy.