PPS ORIAN API

2.0.x
(0 reviews)

ORIAN API Versioning and Compatibility

The API Version

PPS will include an API version in the request URL for all ORIAN requests as agreed during the setup process. The API version will identify a major (e.g. v1) release version.

An example request URL might have the form:

PUT https://my-domain.com/anypath/v1/transactions/1234

Backwards Compatibility

PPS will not introduce a new API version for changes that are not considered breaking. In general this forms a requirement on the ORIAN endpoint to follow the Robustness Principle for its implementation:

Be conservative in what you do, be liberal in what you accept from others

Specifically PPS require that the ORIAN endpoint must be implemented to cope with the following API updates that may occur without version update:

  • The addition of new fields may be added to the request without incurring a new API version. The ORIAN endpoint should ignore any unrecognised properties.
  • The addition of new fields may be added to the response without incurring a new API version. Such fields will always be optional and so may be omitted by the endpoint.
  • The set of possible enumerated values that may be sent in a given resource property may be extended without a new API version. ORIAN endpoints should be prepare to ignore any values that they do not expect or to provide default handling. Enumerated values will not be removed and the meaning of values will not change for a given API version.

API Versioning Strategy

PPS will continue to send messages formatted according to the agreed API version for the ORIAN endpoint (with the exceptions defined above) regardless of the availability of new API versions.

PPS will create a new API version only for changes that are considered 'breaking'. Such changes include:

  • Changes to property names or types.
  • Removal of enumerated property values or a change to the name or meaning of an enumerated value.
  • The change of the type or format of a property value.
  • Addition of mandatory properties.
  • Removal of mandatory properties.

To take advantage of capabilities provided in versions integrators should contact PPS to schedule a version upgrade.

API Version Support

At present PPS define no restriction on the continued support of older ORIAN API versions.

Reviews