Versioning

Updates are good, here's how we manage them.

Purple gradient wave Purple wave used to give a visual break between the header and body of the page.

Summary

Software is constantly evolving and we don't intend to stand still either. We will be regularly working on new features and improvements to give you access to the full functionality of Youmanage through a simple and convenient API.

In order to do this and to ensure we can move forward without breaking any existing applications that have been created, we will be releasing functionality incrementally.

This document details how we plan to release these versions, how long they will be supported for and .

 

Version Format

The API uses Semantic versioning which is a 3-component number in the format of Major.Minor.Patch, where:

 

Beta

The API is currently still in the development phase and as such will be subject to change. While we endeavour to make changes with minimal impact there is a small chance that new versions in the 0.x.x series may, in contradiction with the general versioning policy, introduce breaking changes. As with all releases, we will notify you of upcoming features, improvements and breaking changes in advance so that provisions can be made.

Once we have completed our initial phase of development and the API has reached it's first stable version of 1.0.0 the standard versioning rules will apply.

While we don't anticipate any problems during the beta phase, if you should encounter any issues during this period we would be grateful if you could work with us by providing a detailed report of the problem, to enable us to get a fix out as soon as possible.

 

Lifetime Policy

The current version of the API will be the focus of any future development work and will receive product enhancements and bug fixes.

When a new major version is released, we will provide access and support to the previous version for a suitable amount of time before deprecating that version to enable developers to migrate to the newer version. These versions will not receive any further product enhancements but will still receive patches for any critical bugs.

Once a version has been deprecated it will be supported for a further 6 months after which time you will no longer be able to request it. Any requests to an unsupported version will result in an error being returned.

 

Selecting a Version

The default version of the API will be the most current version that will be used, unless another version is specified.

You will be able to request a specific supported version of the API by sending an additional header in the request and we encourage you to do this to ensure there are no breaking changes between versions.

Details of which versions are supported and which have been deprecated will be returned in the request headers:

curl -iH "x-api-version: 0.1" "https://api.youmanage.co.uk/"
HTTP/1.1 200 OK
api-supported-versions: 0.1
Date: Fri, 16 Aug 2019 07:41:35 GMT

         

Troubleshooting

If you are receiving an Invalid Version (YM0073) response, it may be caused by either requesting a version that is not currently supported (the above will explain how to find out which versions are currently supported); or you have sent an invalid version number (see above for the correct format of version number).

The following is an example request for an invalid version number 2..4 and a sample response from the API:

curl -iH "x-api-version: 2..4" "https://api.youmanage.co.uk/"
HTTP/1.1 400 Bad Request
Date: Fri, 16 Aug 2019 07:52:52 GMT

{
  "error": {
    "code": "YM0073",
    "reference": "https://developer.youmanage.co.uk/api/errors/ym0073",
    "target": "Version",
    "message": "An invalid version was requested",
    "details": null
  }
}

Next up we'll be looking at rate-limiting - how the API controls the numbers of requests that can be sent.

Back to all guides