UI Versioning

UI Versioning

We maintain versions on the _ui/ api so that we can deploy breaking changings to the UI API without causing any downtime on cloud.redhat.com during deployments.

The api is versioned using DRF Namespace Versioning, which is defined in galaxy ng here. Versions are determined via URL, so _ui/v1/ corresponds to version v1 and so forth. The acceptable version numbers are defined in galaxy_ng.app.constants.ALL_UI_API_VERSION.

Viewsets are versioned by defining their versioning_class, as shown bellow:

class TagsViewSet(api_base.GenericViewSet):
    serializer_class = TagSerializer
    permission_classes = [access_policy.TagsAccessPolicy]
    versioning_class = versioning.UIVersioning

Doing so will make the current API version number available via self.request.version. This can be used in a viewset to modify the API to behave differently based on which version of the API is being called. For example:

class TagsViewSet(api_base.GenericViewSet):
    [...]
    versioning_class = versioning.UIVersioning
    
    def get_serializer_class(self):
        if self.request.version == 'v1':
            return OldTagSerializer
        return NewAndImprovedTagSerializerWithBreakingChanges

In this example we can create a new tag serializer that has breaking changes for all newer versions of the api, while retaining the old serializer for compatibilty.

The UI only cares about the current version and previous version, so any older version of the API can be deleted once they are no longer needed. VERSIONING ON THE UI ENDPOINTS DOES NOT MAINTAIN BACKWARDS COMPATIBILITY FOR ANYTHING OTHE THAN THE GALAXY NG UI. The _ui/ APIs are not supported and we retain the right to change them however we want, whenever we want.

Updating the UI API version

When should the version be increased?

Whenever any breaking changes need to be made on the API. This includes any:

• field deletions
• existing field schema changes
• url changes

How do I increase the version number in the API?

Update galaxy_ng.app.constants.ALL_UI_API_VERSION to contain the new version you wish to add.

ALL_UI_API_VERSION = {'v1': 'v1/', 'v2': 'v2/'}

Update galaxy_ng.app.constants.CURRENT_UI_API_VERSION to whatever the latest version is. Note the unit tests are automatically run on whatever the latest version of the API is.

Make the required breaking changes to the serializers using self.request.version as described above. Changes only need to be made on viewsets that have to behave differently between different versions of the API.

How do I increase the version number in the UI?

Simply update UI_API_VERSION in the BaseAPI class to whatever version of the API you wish to use.