Skip to main content
Version: v2alpha1

Versioning

getpaid API requires regular updates to its contract to adapt to the evolving needs of users. The majority of modifications introduce new functionality without requiring a new API version, maintaining compatibility with the existing API. However, when a disruptive change is essential within the current version, a new version is released. Effective versioning is essential to simultaneously support and sustain multiple live versions.

Implementing versioning​

Versions are specified in the URL https://api.getpaid.com/{version}/, ensuring that the path of each resource remains unchanged from that version number onward.

Different versions of the API come with varying support and stability levels, each described below:

  • Alpha:
    • The version format is vXalphaY (e.g., v2alpha1).
    • The product is actively in development after the previous software release.
    • Any feature may be removed or undergo breaking changes without prior notice.
    • Only available for specific clients, recommended for testing new features, subject to future modifications.
    • No long-term support.
  • Beta:
    • The version format is vXbetaY (e.g., v2beta1).
    • Tested features are secure for use.
    • Features may be removed or undergo breaking changes, with advance communication and a provided migration plan.
    • General availability, recommended for testing new features and feedback.
    • No long-term support.
  • Stable:
    • The version format is vX (e.g., v2).
    • Features cannot be removed or undergo breaking changes.
    • The final product is released to the general public.
    • Long-term support is available, with advanced notice of end of support and a migration plan to the latest version.

Tolerant reader​

Tolerant reader is a design pattern aligned with the robustness principle (Postel's Law), emphasizing being conservative in what you send and liberal in what you accept. This implies that you should only extract the information your system needs and only fail if a required field is not present in the response.

As part of our versioning strategy, getpaid API is designed to evolve with users needs and be forward compatible, meaning that it should be possible to add new fields to the API responses. API responses should be consumed selectively ignoring unnecessary fields. Failure to implement a tolerant reader may result in system downtime, failure, or improper functioning due to changes.