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 maheshkumar.palavalli - so thanks to him 😉
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?
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
Here’s the how-to description:
Create an API with the following model
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:
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 a new file containing the following CDS
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
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
And it is inspired by maheshkumar.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
- SAP Managed Tags:
4 Comments
