Quicklinks:
First route
Sample project files
In this tutorial, we want to go the next step towards a productive application development.
Enterprise applications in SAP Cloud Platform typically have an application router as main entry point.
The App Router can serve a static web page (e.g. homepage), or just redirect to the web application itself.
Big advantage is: the app router can be used for Authentication.
And even better: the user login can be reused.
We will have a closer look at it.
In our series of Tutorials about SAP Cloud Platform Backend service, why are we covering App Router?
Yes, why?
Because App Router plays a role in a scenario where Backend service is used as backend by a front-end application.
Ouw, that’s too much for now
True, let’s first learn the basics about Application Router
What is it, the App Router?
The App Router is really just an approuter
What does it mean?
An end-user opens the browser and type a fancy URL like
https://nice
The App Router routes the URL to the concrete URL of an existing application, e.g. https://app/internal/ugly
So, an approuter is just a forwarder?
Sure. A forwarder
It is a delegator
It is like a redirector (you'll see it below)
Or we can say: it is a router
Even an app router?
Yes
How does it look like?
The app router is an existing node.js application
Since routing is a rather simple job, we can use the default implementation available for SAP Cloud Platform Cloud Foundry Environment
How can that be done?
Download the node.js package
Configure
Deploy
Any other benefit?
The App Router can take over one very important task for us:
Authenticate the end-user, before doing the routing
App Router does the oauth flow
If we configure that
Great, can we start?
Yep
As usual?
Yep: to get started, we use a very simple example
I like simple. It is good learning experience
My words...
Goal
Learn how to use the Application Router in SAP Cloud Platform, Cloud Foundry Environment
That is: deploy the Application Router and define routes
More goals in part 2 and 3
Prerequisites
No coding skills required
node.js:
The existing Application Router is a node.js application, available for download.
As such, we need node.js installed on our local machine
You might want to have a look at this section, where I’ve already described the necessary steps to be prepared to run node
The App Router package is available for download from the SAP npm registry.
As such, it is necessary to configure the npm registry, as described there
Deployment
Our App Router needs to be deployed to Cloud Foundry.
You can use the Command Line Client or deploy from the Cockpit, as described in this blog
Preparation
We’re going to create a Cloud Foundry application which wraps the existing App Router package
You were telling that the App Router is an app?
That was little imprecise
The existing App Router is a node.js application, but not a Cloud Foundry application
Ah..
As such, we need to create our own app, to be deployed to Cloud Foundry
Our own app contains the existing App Router, we don't write any code
Our own app is a node.js app which has a dependency to the existing App Router.
After deployment, our own app is used to start the existing App Router
Create project structure
Create a folder, e.g. c:\tmp_approuter
In the tmp_approuter folder, create a file manifest.yml
Still in tmp_approuter folder, create a subfolder called e.g. appfolder
Step into the folder appfolder
In the folder appfolder, create a file package.json
Still in the folder appfolder, create a file xs-app.json
Install App Router package
Installation is done by declaring the dependency to the existing App Router package
Afterwards, the node package manager (npm) will install it
Open the file c:\tmp_approuter\appfolder\package.json
Paste the following (minimalistic) content
{
"name": "myapprouter",
"scripts": {
"start": "node node_modules/@sap/approuter/approuter.js"
},
"dependencies": {
"@sap/approuter": "^6.0.1"
}
}
Note:
You can see that the start script command points to a javascript file in the downloaded package of approuter
This means:
After a node.js app is deployed to Cloud Foundry, the "start" script is automatically executed. In this case, it will start the existing App Router
Now, to install the existing App Router, go to a command prompt, navigate to the directory C:\tmp_approuter\appfolder
Then run the following command:
npm install
Alternatively: npm install –save
This will add the node_modules folder and inside is @Sap and finally the approuter folder
The approuter folder is the existing App Router?
Yep
Finally, our project structure looks like this:
C:\tmp_approuter
manifest.yml
C:\tmp_approuter\appfolder
node_modules
package.json
xs-app.json
Learning 1: very simple route
Our goal for this learning: ---> Define a route to sap.com
That’s it. Very simple
This implies:
We create our Cloud Foundry application
Our application contains the downloaded approuter and a configuration
We deploy our approuter configuration app
After deployment, our config app will get a URL (the host-URL, see below)
We call this URL
And <woush> ---> we see sap.com
So the only thing we need to do: configure the existing App Router
Configuration is done mainly in xs-app.json
More precise:
Configuration is done with 2 files: manifest.yml and xs-app.json
Why 2 files?
Let’s see:
xs-app.json
This is the application descriptor.
In this configuration file, we define the routes
A route basically consists of a source URL which is routed to the target URL
I easily get confused
I always got easily confused trying to understand existing approuter configurations
I think, in order to understand the route definition, we have to take over the role of the approuter
Means empathy?
Similar
We have to act like an approuter
We're in the middle
We receive incoming calls
So, the "source" is the source of an incoming call
We delegate the incoming call to the target
Still confusing
I think the still-confusing part is that the source URL is defined by us.
Why?
Because we can define multiple redirects, depending on the source
E.g.
If user types http://nice then we redirect to http://app/internal/birdies
If user types http://beautiful then we redirect to http://app/internal/cats
Such kind of "rule" is what we define in the xs-app.json file
Now, open the empty file C:\tmp_approuter\appfolder\xs-app.json and paste the following content:
{
"authenticationMethod": "none",
"routes": [
{
"source": "^/(.*)$",
"destination": "env_destination_saphome"
}
]
}
Explanation:
"authenticationMethod": "none"
This setting declares that our App Router configuration doesn’t require authentication
No user login screen is presented when the URL of our app is opened
As per default, authentication is enabled. Let’s disable it, it makes the effect of approuting more amazing
routes
Multiple routes can be declared by one App Router configuration
route
One route defines one route
Stupid explanation
One route contains the definition of how a source URL should be forwarded to a target destination
source
Here we define the URL that can be typed by a user who opens the approuter application
E.g.
https://<approuterName><cloud>/some/source/url/segments/index.html
We can also understand it like an endpoint which is exposed by our app
In our first example, it is very simple: it is just everything
The URL is described by a regular expression:
e.g.
^/(.*)$
In our example it means:
Anything before a slash
Then the slash
Then anything before the end
So our user can call our approuter-app without any path segments. He will be always forwarded
"destination": "env_destination_saphome"
The second property of the route defines the target destination, to which the user will be forwarded
Now, we have to understand that the App Router is meant to be used in enterprise application development.
As such, it would be too easy to just type a URL as a target destination.
What's the problem with too easy?
No. An enterprise application has to be powerful and flexible
As such, the target URL has to be variable
In fact: the value of the property “destination” is the name of a variable
It is an environment variable
It must exist.
There must be an user-defined environment variable with exactly that name
OK
Now, an environment variable can be created manually.
It can be done in the SAP Cloud Platform Cockpit, or via command line
It must just be there, when the app is called
However, for us, the most comfortable way: to define the environment variable in the manifest.yml file
So now it is time to create that manifest
manifest.yml
Open the empty file C:\tmp_approuter/manifest.yml and paste the following content:
---
applications:
- name: myApprouterConfigurationApp
host: myapprouterconfapp
path: appfolder
memory: 128M
env:
destinations: >
[
{
"name": "env_destination_saphome",
"url": "http://sap.com/"
}
]Note:
Don't forget that it is a yml file, every blank and indent must be correct
Explanation
name: myApprouterConfigurationApp
We define a name for our app which we deploy
The name I’ve chosen is long and ugly, but it is meant to make clear that:
Our app is a wrapper for the existing approuter and our app contains configuration for it
env:
Here we set the environment variable with name “destinations”
It can contain a list.
In our example, we provide only one destination entry
The destination entry must have 2 mandatory properties: name and url
"name": "env_destination_saphome"
The name is the name
To be more concrete: the name is the name which is written in the xs-app.json file
As usual, my names are ugly, but they try to make things more clear
So in this case, the value of the name property is "env_destination_saphome"
It shows that it is an environment variable for a destination and it points to the SAP homepage
"url": "http://sap.com/"
The url property is FINALLY the real actual target URL
The App Router forwards the call to this URL
In our example, the final target destination URL is the SAP homepage. Just as example
Deploy
At this point in time, we’ve maintained the approuter config file and we’ve provided env variable in the app manifest
Our app contains the App Router package (in the node_modules subdirectory) and a valid package.json file which defines the start command to start the App Router in the cloud
As such: we’re ready to deploy
As you know, you can deploy with command line or using the cockpit to upload a zip
Run our app
After deployment, open the cockpit and navigate to the app overview page
??? Why Application Routes?
Don't be confused.
In Cloud Foundry, an application can have multiple URLs, that's why they call them "Routes"
It has nothing to do with our App Router routes
Then click the app link
The result: we don’t see any approuter or xml or whatever: we see directly the SAP homepage:
It is a nice coincidence, that the official SAP homepage celebrates our sweet success of having created our first App Router….. ?
Just kidding
Done?
Let’s do one last little exercise:
Open a new browser window and open the "Developer Tools" (usually pressing F12).
In the dev tools, if necessary, open the tab for “Network”, to monitor the network traffic.
Back to the browser window, paste the URL of our application into the browser window.
It is the same app URL like shown in the screenshot, in my case:
https://myapprouterconfapp.cfapps.eu10.hana.ondemand.com/
Then check the developer tools
(you might need to scroll up to the first request)
We can see that the first request has called the URL of our approuter-config-application.
Click on the request to see the details on the right side
We can see that the status is “301 Moved Permanently”, which means that a redirect has occurred
Check the “Response Headers” section
We can see that there’s a “Location” header and the value is “sap.com”
Is that good?
All that is expected.
That’s what we declared in our App Router configuration: the redirect from our app-URL to
---> sap.com
Summary
The end-user types a URL in the browser: that’s the source
Allowed source URLs are defined by approuter configuration
The approuter redirects the end-user to a target URL
The target URL is defined by approuter configuration and specified in a destination
Next Steps: Learning 2 and 3 and 4 and 5 and 6 and 7 and 8 and 9
Links
SAP Help Portal: Application Router documentation entry page
Don't miss this one: https://www.npmjs.com/package/@sap/approuter
Overview of tutorial series
Appendix: Sample Project Files
package.json
{
"name": "myapprouter",
"scripts": {
"start": "node node_modules/@sap/approuter/approuter.js"
},
"dependencies": {
"@sap/approuter": "^6.0.1"
}
}
manifest.yml
---
applications:
- name: myApprouterConfigurationApp
host: myapprouterconfapp
path: appfolder
memory: 128M
env:
destinations: >
[
{
"name": "env_destination_saphome",
"url": "http://sap.com/"
}
]
xs-app.json
{
"authenticationMethod": "none",
"routes": [
{
"source": "^/(.*)$",
"destination": "env_destination_saphome"
}
]
}- SAP Managed Tags:
30 Comments
