SAP Cloud Platform Backend service: Tutorial [32]: Easy API versioning

This blog is part of a series of tutorials explaining the usage of SAP Cloud Platform Backend service in detail.
And it is inspired by Mahesh Kumar Palavalli – so thanks to him 😉

Quicklinks:
Quick Reference

Why versioning an OData service?

Usually, a service is used like a public API. It is not meant to be used by a human, who requests the service on a need basis, because he wants to have a look at the nice xml
He can request the json format, which is more human readable.
A json response isn’t meant to be read by humans either

Instead, services are called by programs, or by applications.
Where’s the difference?
A human person, occasionally calling a service, can live with structural changes.
However, as soon as the response of a service is read (parsed) programmatically, the structure of the response must not change.
Never?
Never.
Otherwise the program or the application would break
Furthermore, OData services do expose their structure in the so-called metadata-document (addressed via service/$metadata)This is like a contract and app developers rely on it
But my service is bullsh…
That’s not my problem
But what can I do?
As usual: read my blogs.
I’m reading, but nothing is…
The solution is:
Publish a new version of your service
Good idea, but I guess that’s complicated
Nono, using Backend service it is very easy
Great, I want to do it
No more questions?

How to call an OData service with specific version?

This is achieved by adding the version parameter to the root URL:
http://…/myservicename;v=2

In my example:
https://backend-service…/odatav4/DEFAULT/PRODUCTSERVICE;v=2/$metadata

Cool, so easy
Yes,
OK, I’ve tried it but I get an error:
API with name PRODUCTSERVICE, …and version 2 does not exist
No no, it is not THAT easy, you have to create the new version yourself

How to create a new version in Backend service?

Here’s the how-to description:

Create API with version 1

Create an API with the following model

service ProductService {

    entity Prodcuts{
        key produDI : String(10);
        nam : String(1024);
        desc : String(1024);
        pric: Integer;
    }
}

The model is ugly
That’s intended

Note:
If you’re missing a guide on how to create an API, you may want to look here

Note:
If you already have an API, you can go to the Backend service cockpit, navigate to your API details pane, go to the “Documents” section and choose an action to view or download the model file

After publishing the API, look at it and feel ashamed, because you notice the stupid names and typos.

Nevertheless, there are already hundreds of app developers in the world who have created apps based on your API.
Such UI5 apps contain lines like follows:

 <List items="{
     path : 'productModel>/Prodcuts'
   }">
   <items>
      <ObjectListItem 
         title="{productModel>nam} - (with ID: {productModel>produDI})">

We can see that the typos in our model are used in the application code.
That’s because the entity name and the property names are used for binding in UI5
(See here for little sample)

I want to fix the typos in my API
If you modify your API, the UI5 application wouldn’t work, it would be empty, because all the bindings wouldn’t be found

As such, you go for the proposed solution: Create a new version of the same API

Create same API with version 2

Create a new file containing the following CDS

service ProductService {

    entity Products{
        key productID : UUID;
        productName : String(20);
        description : String(1024);
        price: Decimal(2,2);
    }
    
    entity CustomerEntity{
        key customerID : Integer;
        companyName : String;
        linkToContact :  Association to ContactEntity;
    }

    entity ContactEntity{
        key contactID : Integer;
        contactName : String;
        contactPhone : String;
    }
}

We can see that several incompatible changes have been introduced in entity Products:
E.g. Entity name, property names, data types, max-length facet

Furthermore, the model has been enriched with more entities. But theywouldn’t have broken the UI5 application

Create version 2:

Go to the Backend service cockpit and create “New API”.
In the “Name” field, enter exactly the same name like the API with version 1 created in previous step
Also “Namespace” must be the same
Enter version 2
Versioning like 1.0.2 is not possible
Browse to your new cds model
Finally, press “Create API”

As a result,the cockpit shows twice the same API, but with different version

Your API has now 2 URLs, with different version parameter:

https://…backend-service…/odatav4/DEFAULT/PRODUCTSERVICE;v=1/$metadata
https://…backend-service…/odatav4/DEFAULT/PRODUCTSERVICE;v=2/$metadata

You can compare the metadata and you’ll see that the second version looks better

The good thing: you haven’t broken any UI application
The hundreds of users of your service have now the choice to switch to the new version whenever they like

Summary

To create a new version of an existing API, proceed as follows:

Create a new API
-> Specify exactly the same name (and namespace)
-> Specify an incremented version number

That’s all