Skip to main content

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.

Purpose​

The NomuPay API needs to update its contract from time to time to stay current with a merchant's requirements. Versioning is essential for keeping various products alive when a breaking change is implemented in the API contract.

note

A new version will be released if a breaking change is required.

Implementing versioning​

Versioning is implemented in the URL https://api.nomupay.com/{version}/payments, meaning that the path of each resource won't change from that version number forward.

The different versions of the API involve different support and stability levels. Each level of criteria is described below:

  • Alpha level:
    • Name contains alpha: vXalphaY where X and Y are integers. Example: v1alpha1.
    • Product is actively in development after the previous software release.
    • Any feature can be removed or suffer breaking changes without previous notice.
    • It is only available for certain clients. Only recommended to use to test new features and they can suffer modifications in the future.
    • There is no long-term support.
  • Beta level:
    • Name contains beta: vXbetaY where X and Y are integers. Example: v1beta1.
    • Features are tested and can be used securely.
    • Features can be removed or suffer breaking changes. If that happens, it will be communicated in advance and a migration plan will be provided.
    • General availability. Only recommended to test new features and share your feedback. Once the version moves from beta level to stable level, new features or changes will be limited.
    • There is no long-term support.
  • Stable level:
    • Name is vX where X is an integer.
    • Features cannot be removed or suffer breaking changes.
    • The final product is released to the general public.
    • There is long-term support. End of support will be communicated with advanced notice with a migration plan to the latest version.

Tolerant reader​

Tolerant reader is a design pattern used to implement the robustness principle (also known as Postel's Law) defined in RFC1122.

Robustness principle​

The 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.

Understand tolerant reader​

The NomuPay API 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 NomuPay'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 NomuPay 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.

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 changes.