API Versioning

Introduction

Wave Framework allows you to version your API so that when a new Controller, Model or View becomes available and causes potentially backward-compatible breaking situations, then you can tell the system to fall back to those files of the older version, rather than use the newer version files.

An important thing to keep in mind is that it is necessary to sometimes make sure that your database is also versioned, especially if your Models become incompatible with your newer versions. THis document gives some ideas about to achieve this as well.

There are three types of version numbers for Wave Framework. First is the version of Wave Framework itself, written in PHP version number style, like 1.0.0, 3.7.1 and so on. Second version number is 'system' version number, which is used to define version numbers for your own software. This second version number is written the same way as PHP version number and is 1.0.0 in default installation. The third version number is for API and is written as 'v1', 'v2' and so on. This is because this version number is for API specification and can be used to request different versions over API.

Version numbers are stored in '.version' file in the root folder of your installation. There is also a configuration setting 'api-versions', which lists the version numbers which are allowed to be accessed over API. Note that API versions can have any kind of name, including 'beta' and more, but only latin characters and numbers are allowed. Character of '.' is also not allowed as part of an API spec version number.

Versioning Classes

Sometimes it is necessary to keep a Controller, Model or View file due to refactoring or backwards-compatibility-breaking changes in code. Wave Framework allows you to version your MVC classes by version numbers. To set up proper versioning you should first edit the configuration option 'api-versions'. For example, if you want to version your current 'controller.example.php' file from '/controllers/' folder, then you can change the configuration option to 'v2,v1'.

The first value in the 'api-versions' setting is considered the most current API version and the other version numbers are allowed to be accessed over API. If you wish to disable some version entirely, then remove them from the list.

By changing this value to 'v2,v1' you are telling Wave Framework that the files in the root folders of '/models/', '/views/' and '/controllers/' are considered 'v2' of your API. If you append 'v3' to the list, then automatically the files in the root are considered 'v3'. This means that the API will always fall back to the most recent version, if certain Controller, Model or View is not found for the requested version.

Now in order to version your 'controllers.example.php' file, you should create a new folder in your '/controllers/' file, called 'v1' and add that file to that folder.

This now means that if an API request is made that has 'www-version' set to 'v1', and that particular Controller is requested, then the system will load the Class from '/controllers/v1/controller.example.php' instead of '/controllers/controller.example.php'.

Note that versioning is also supported for overrides folders and similar logic can be applied to files in '/resources/libraries/' and '/resources/classes/' folders.

Versioning Databases

Database versioning is one of the more complicated parts of versioning, since it is often necessary to version different users of API that are all tied to the same core database, without breaking functionality. This is a tricky subject that depends highly upon how your system architecture is built, but Wave Framework does allow you to check the API version of your requests within Controllers, Models and Views and allows you to make changes accordingly, based on API version.

To find out what version is currently being requested from the API, you can use the following method through the Factory:

			
	$this->apiVersion();
	

This returns the value that was sent with 'www-version' when making an API request, or just returns the current API version number.

Complete Versioning

Sometimes it is necessary to version more than just your MVC files. For example, when your entire system gets massive changes in other folders too, such as from '/resources/' and '/engine/' folder. In this case it is recommended to make a full copy of the entire installation folder and set it either to a different subdomain or in a subfolder and accessed this way. So that your API requests that used to be 'www.example.com/json.api' will now go to 'www.example.com/old/json.api' instead.