Versioning

📘

How to stay up to date

This article details our API versioning process.

Updates made to the API reference are published in an RSS feed: https://developers.acehubpaymentservices.com/changelog.rss

What is Versioning?

Versioning is the creation and management of multiple releases of a product, all of which have the same general function but are improved, upgraded or customized.

Why Versioning in the AceHub API?

AceHub API needs to update its API contract from time to time to keep up-to-date with the merchants' requirements. Versioning is essential for keeping various AceHub products alive when a breaking change is implemented in the API contract.

How is Versioning Implemented in the AceHub API?

Versioning is implemented in the URL, meaning that the path of each resource won't change from that version number forward.

Example: Body changes in different API versions

Old URL (v3)

https://stagconnect.acehubpaymentservices.com/gateway/v3/payments
{
   "myURL":"test.com"
}

New URL (v4)

https://stagconnect.acehubpaymentservices.com/gateway/v4/payments
{
   "yourURL":"test.com"
}

Tolerant Reader

Tolerant Reader is a design pattern used to implement the Robustness Principle (also known as Postel's Law) defined in RFC1122.

What does the Robustness Principle Mean?

Robustness Principle is a general design guideline for software, stating the following:

"Be conservative in what you do, be liberal in what you accept from others", often reworded as "Be conservative in what you send, be liberal in what you accept".

This means that you should read only what your system requires in order to allow the API response message to properly perform the business logic. Also, your system should fail only if a required field is not present in the API response message.

Why Tolerant Reader?

AceHub is evolving constantly to fulfill our merchants' needs, hence the API messages will be updated from time to time (by adding new fields) to meet this goal. Based on their importance, the fields we add can be mandatory or optional. For mandatory fields a breaking change will be added to the API messages (request/response), thus creating a new version of the API. On the other hand, optional fields don't require an API version update.

Therefore AceHub's clients must be forward compatible and implement the tolerant reader design pattern to be able to harmlessly read future API messages.

Recommendation

Our recommendation to our merchants is to be as tolerant as possible when reading data from the AceHub API. When consuming the JSON response message, you should only take the elements you need and ignore the ones you don't need. Furthermore we recommend you make the minimum number of assumptions about the structure of the JSON message you're consuming.

On top of this please make sure that there's only one bit of code that reads data payloads like this. A recommended best practice is to use a Data Transfer Object to wrap the data payload behind a convenient object so the rest of your system can solely rely on a single object and be impervious to changes that would break even a tolerant reader.

If your system implements a tolerant reader and does not need the new field "yourURL", this change will be completely transparent and harmless.

IMPORTANT: What Happens if I don't Implement a Tolerant Reader?

If you consider not implementing a tolerant reader, your system may experience downtime, failure or improper functioning due to these changes unless you update it in a timely manner.