Skip to content
×

Versioning

Overview

The API is versioned using a major.minor version numbering scheme. An optional suffix is used to indicate alpha or beta releases. A version string takes one of the following forms:

m.n or m.0-alpha or m.0-beta

The major version (m) is embedded in end-point URLs. The minor version (n) and any alpha/beta suffix are available via GET query.

The point of versioning is to support the definition of, and commitment to, backwards compatibility. Briefly:

Info

Well-behaved client scripts written against API version m.n will continue to work, unmodified, as the API evolves through minor revisions m.n+k for positive k.

Upgrading to a new major API version m+1 may require modifications to client scripts, but major API versions m and m+1 will co-exist for a — potentially indefinite — transition period. Within business reason, the decision on when to upgrade to a new major API version should rest with the client script owner.

The bullets below describe in more details the changes we allow in the API as well as the notion of a "well-behaved" client script.

  • Additional major API versions can be added. There is no requirement that API m+1 be compatible with API m, but the two must be available side-by-side until a business decision is taken, if ever, to sunset the older one. Sunsetting can happen only after a reasonably long and publicly announced transition period, involving due consideration for the number and business engagement of API m users.
  • Each major API version m will be in alpha or beta during its early life, as indicated by a suffix on the version number: m.0-alpha or m.0-beta. While m is in alpha or beta, anything can change, and the minor version number remains at 0. In practice, alpha means less stable than beta. An alpha API should be used only by clients collaborating closely with JADBio staff. Once the suffix is removed, the m.0 API is considered "generally available". From that point on, the minor version number will be updated on API revisions, and the API is subject to the compatibility constraints described here.
  • Additional API end-points can be added to any API version.
  • Well-behaved clients do not depend on API end-points being currently absent.
  • Additional allowed values can become supported in request objects in any API version.
  • Well-behaved clients do not depend on request values being currently invalid.
  • Additional optional fields can be added to request objects in any API version.
  • Well-behaved clients do not depend on request fields being currently ignored.
  • Additional fields can be added to response objects in any API version.
  • Well-behaved clients do not depend on response fields being currently absent.
  • Additional values can become used in response object fields in any API version, provided the documented type/range of that value does not change, or provided the additional values can arise only in responses to request sequences that were not previously supported by the API.
  • Well-behaved clients do not depend on undocumented response value constraints.
  • A well-behaved client script is considered broken by an API change only if there exists a particular end-to-end execution of that script, with all inputs defined, that works before the change and does not work afterwards, for the same inputs. Such breaking API changes are not allowed between API versions m.n and m.n+1.

The API is considered defined by its documentation on the present pages, not by its current implementation. In particular, bug fixes and analytical performance improvements are not considered API changes.

Get version

Provides access to the full version number of the currently deployed API. The major version number is always implied by the request URL.

Request:

GET /api/public/v1/version

Response:

{ payload: { version: string }, status: "success" }

Example

$ http --body https://jadapi.jadbio.com/api/public/v1/version

{
    "payload": {
        "version": "1.0-beta"
    },
    "status": "success"
}

Note

The client examples in this document use the command-line tool http (httpie.org). An often-used alternative, with more arcane syntax, is curl (curl.haxx.se).


Note of appreciation to JADBio users

We constantly make changes in the software and do our best to update these materials, but you may notice some differences. We welcome your feedback on how to make this more useful for you and requests for future tutorials.