Dear friends of APIs, welcome to this blog post which aims to help you doing your very first steps to easily create your own API in
SAP Cloud Platform
Why do you need an API?
Well, first of all, because it feels good
😉
And because it is easy
And maybe, because you want to provide a brand-new service which others can use to build an application on top of it
Still need more info?
Well, you can click on this
link to read the introduction
You prefer the chilled way?
Enjoy
this introduction video
You don't like links?
Here's my summary:
Using this offering, you can create an OData service without any coding.
You only need to provide a model file
The resulting OData service can be used to store and read data without configuring a database
Interested?
So read this blog and what you’ll be doing is:
- Enter your SAP Cloud Platform Cockpit
- Go to your Backend service
- Give your model
- Get an OData service
That’s it: Just 4 steps to do
Ohhh, it is still looking like much effort?
4 Steps are too much???
OK, then let’s phrase it differently:
- Give your model to your Backend service and get your OData service immediately
That’s it. Really easy, isn’t it? Just one step to do…
Preparation
As usual, few preparation steps are required.
You need access to SAP Cloud Platform. If you don’t have, you can try it.
Get your free Trial
Right now, the SAP Cloud Platform Backend service is a beta and
has to be enabled for usage
Before really using it, you need to
configure roles
This blog is part of a
series of tutorials.
Create your first API
Go to your Backend service in the cloud.
You've probably bookmarked the link, it looks similar to this:
https://yoursubaccount-backend-service.cfapps.eu10.hana.ondemand.com/cockpit/
Otherwise, start with your cloud landing page, e.g. Trial:
https://account.hanatrial.ondemand.com
Click on "APIs" in the navigation pane
Press the button "Create API"
In the "Create API" dialog, enter the following information
The CDS document which is required in the dialog, has to be uploaded from your local file system
So you have to press the Browse button and navigate to a file with file extension .cds
Then press on the but….. oh…
You don’t have such file???
Oh, how surprising…
I have a file, I can hand it over to you.
Give your (my) model
If you don’t have a model file, you can proceed like this, to create it:
Go to your local file system, create an empty file and paste the following content into it:
service MyFirstService{
entity Products {
key ProductId : Integer;
Name : String;
Category : String;
}
}
Save it as MyFirstService.cds
Note:
See here for a description of tools which support the creation of CDS model files
Now you can go back to Backend service.
Again, open the dialog to Create API again, enter the required information again and now choose your model cds file
Then you can go ahead and press ….
....I don't hear an “ohhhh”.... ? …
Good.
So finally press it, the "Create API" button in the right corner of the dialog
And wonder what’s happening.
You get an error message like me?
Don’t worry, don't panic, before you go to search the logs for the reason, just guess that your session has timed out.
So close the error popup and reload the browser and repeat the creation if necessary.
After successful creation, you can see your service listed in the APIS list of the cockpit.
You can quickly press the logs button and monitor the process of generation by keeping refreshing the dialog
You can also click on the refresh button to refresh the list of APIs and so refresh the state of the activation status of the new API
Overall, I think the creation of the API is really fast, taking in consideration that really a lot of stuff is happening under the hood
Finally, you've created your first API.
It is a nice little OData service
View your first API
Yes, you’ve already viewed it, but only in the list of APIs.
There’s more to view.
So click on the row to go to the details screen
Now view your API.
All of it.
But only view it, OK?
Don’t touch…
Why? See next section
Test your first API
Because now, THIS is the right chapter for touching your API...
Your API is an OData service, you’ve seen it in the first section of the API details screen.
As such, it can be accessed via URL
You can do it either in a browser.. or… do it in a browser, but using the
Backend service cockpit
For convenience, the Backend service cockpit offers a piece of UI that helps you exploring your new API.
It makes things easier, you’ll figure it out while playing with it
Note:
if you get authorization error while invoking your service, you might have missed the role - blog
Scroll down to API REFERENCE
This whole section, I would consider it like a testing tool, which helps you to test your API
There is a sub-section called "Products", which is the name of our entity which we defined in our model.
For the entity, there are several operations available, like GET, POST, etc
These operations are supported by the OData specification
Afterwards, there’s a section called "Models" and another one called "Events". Please ignore them. Just ignore and forget them.
You remember the Models section?
- No
(correct answer)
Now click on GET
It turns out that this is a whole section which is expanded.
The section lists and explains possible URL parameters
And it also shows you how the response of your API is structured and how it would look like
Don’t try to understand why the default response is “Error”
Just ignore and forget it.
Remember: it works (I mean: it works to forget…)
The best of all: the button “Try it out”
Click it
All the parameters turn into editable state
Leave them for now
Instead, click on "Execute" right away
The GET request to the "Products" entityset is executed
Then, scroll down to the “Responses” section
There you can see the “server response” and the code 200 and the “Response body”
The body is empty, I mean, it contains an empty json array []
That's because there's no data to display. But that doesn’t matter...
Think positive:
We have a success response !
Or let’s phrase it like a hero:
We have easily created a great API and we’ve successfully tested it
Next Steps
Stay tuned, more tutorials will be created...
Using the testing tool in detail
Explaining CDS
Associations 1
Associations 2
Property Facets
Custom Types
Model structure 1
Model structure 2
Keep turning to
the overview page