Skip to Content
Technical Articles
Author's profile photo Carlos Roggan

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 😉

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.
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:

In my example:

Cool, so easy
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

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


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'
         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:


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


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

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Mahesh Palavalli
      Mahesh Palavalli

      Thanks for the mention Carlos Roggan … It”s a small and very useful blog..  It will be very friendly if SAP gives an option(button) which creates a new version for an existing service(We can maximize the ux by removing the manual re entry of name and namespace) :).

       (I know I am just an excuse for this blog ? ? But the real reason is that you always wanted to share something to the community right ? ?)

      Author's profile photo Carlos Roggan
      Carlos Roggan
      Blog Post Author

      Hi Mahesh Kumar Palavalli

      (you're welcome - and you really deserve it ?)
      You're right with your proposals - and it could go even together with refactoring capabilities, where you "edit" a model and maybe "save as" new version.


      Author's profile photo Avijit Khandelwal
      Avijit Khandelwal

      Hi Carlos now i dont see the Backend service cockpit in CF.

      How can we achieve this now.

      Author's profile photo Carlos Roggan
      Carlos Roggan
      Blog Post Author

      Hi Avijit,

      please refer to the PN, I've written to you