SAP Cloud Platform Backend service: Tutorial [1]: Easy API creation

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:

1. Enter your SAP Cloud Platform Cockpit
2. Go to your Backend service
3. Give your model
4. 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:

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