Recipe 3: Dipping more toes in

Concepts

As we learned in the previous two recipes, Egeria is a Spring Boot application and uses a file called application.properties to set some common parameters used by Egeria during startup and execution. Its useful to start exploring both what is in this file - and how to override some of the settings. Its also important to understand that each instance of an Egeria OMAG Server Platform often has its own application.properties file - and some of the settings within the file distinguish one instance of the platform from another. We will only touch on a few of the settings in this file - more details can be found on the Egeria website at Platform and Configuring the OMAG Server Platform.

In this recipe we will also start interacting with Egeria by sending it some requests using the REST protocol. Most of you are no doubt familiar with RESTful interfaces - but for those that aren't, you can read up on it here: REST.

OK, with that background we are almost ready to start...we are going to build on what we accomplished in the first two recipes, so if you haven't gone through them yet, now would be a good time to do so! Let's go...

1. Exploring application.properties

In our first two recipes, we worked with an Egeria distribution that we had downloaded and uncompressed into a local directory. On my machine this directory is ~/egeria_sandbox/egeria-platform-4.3-sandbox.gz/. In this directory there is a directory called assembly that contains the files of the distribution. Within assembly is a folder called platform which is the where the jar files for the OMAG Server Platform are. This directory is also sometimes called the working directory. In this directory, you will find a file named application.properties that is used to set properties used by the runtime. Lets take a peek. In the image below I've captured a snippet of text from the beginning of the application.properties file:

Here we can see (after the normal preamble) that we set the property

So if you were curious about why we were using the port number 9443 in our endpoint address of https://localhost:9443 now you know - this is how we specify the default port. If, for example, we already had an Egeria OMAG Server Platform at 9443, we could change this one to be for example 9444. So:

1. Using an editor, open the application.properties file and change server.port to 9444. Save your changes.

2. Lets startup the OMAG server platform by typing:

3. You should see all the normal as the platform starts up.

There are a lot of properties set in the application.properties file. As you can see it is broken into sections that cover how SSL certificates are set up to support inbound and outbound HTTPS (more details at Configuring the OMAG Server Platform), how to set up logging for development time debugging as well as audit and security (note there are a few different mechanisms we often use here) and of course, from the previous lab, you will be familiar with changing the startup-server-list property to establish which OMAG servers to start when the platform comes up.

But what if you want an easier way to change some of these properties? If you just want to test something out or you want to temporarily over-ride one of the settings? Well, glad you asked...that's what we are going to do next.

2. Using command line arguments with the EGERIA OMAG Server Platform

Spring Boot provides us with an easy mechanism to over-ride any of the properties set in the application.properties file. For example, if we wanted to temporarily startup the Egeria Server Platform with port 9447 we could just issue:

And off it goes. So any of the properties in the application.properties file can be over-ridden in the same way. Quite convenient. Of course, the Egeria OMAG Server Platform itself accepts a number of command line arguments that we can use. For example if we want to start the platform outside of the working directory then we need to add a few parameters in our startup command. Lets go ahead and test it out:

1. Stop Egeria (if its started)

2. In your terminal window, cd to another directory; for simplicity I will cd ..

3. Start the platform passing in the loader path (where Java looks for jar files) and the pathname to access the platform. For me, this translates to:

Note that I did do one other sneaky thing - rather than type in the full name of the OMAG server platform jar, I used the * wildcard symbol - saves a bit on typing. Please note that there may be other parameters you might want to change to get the behaviour you desire. The Egeria documentation is pretty rich.

Ok, now that we've got the Egeria platform up and running, lets take it a RESTful break - well maybe not really restful but, sigh, I can't resist the pun. We'll go for a quick spin by sending the OMAG server platform some requests - on to our next step.

3. Taking a RESTful break

The primary way we programmatically interact with the Egeria OMAG server platform is by sending it HTTPS Rest calls. Egeria has a lot of them (100s). They are organized in different functional groupings and documented with Swagger and some other mechanisms we'll review in another recipe. If you want to get a sense of the RESTful requests supported by this platform distribution we can easily do so by opening a local browser to https://localhost:9443/swagger-ui/index.html - if your Egeria platform is listening on port 9443, you will see something like this in your browser (NOTE: It should be safe to ignore a warning from the browser that the site may be unsafe - this is just running a the local swagger viewer):

Feel free to explore the Swagger site - I often spend a lot of time there. If your not familiar with Swagger, its not just documentation - its also a way to test out the requests. However, it can be a little finicky to interpret what you need to feed it. We'll be reviewing some of those details in another recipe. But for now, lets scroll through the Swagger site and look for the Platform Services category. You should find something like this (you may need to play with the little triangular twisties to open up the Platform Services category):

Here we can see a long list of REST services in the Platform Services category. The services use different HTTP commands such as GET, DELETE, POST, to send HTTP requests to Egeria. Egeria processes the requests and sends back an HTTP response. You'll also notice that these requests are just URL fragments - they don't include the first part of the endpoint that identifies the machine and port - you know, the part that says https://localhost:9443. So if we want to make a REST request with this URL fragment we will have to supply the first part. Let's give it a go:

1. Find the service called getServerPlatformOrigin - it will look like the text inside the red box below:

   

If you hover your cursor near the down arrow symbol, a clipboard symbol appears. If you click it, the URL for the getServerPlatformOrigin command will be saved to your clipboard.

2. In a terminal window (not the one where the Egeria OMAG server platform is running) paste in the URL fragment from the clipboard. We'll now have to edit what we put in our terminal window to use the cURL command to execute the request. Edit your command line to look like:

Before you hit enter, lets briefly walk through what we're doing. cURL is a standard command available on many linux and linux-like operating systems that allows us to make an http request. The rest of the line contains the URL for the endpoint and the request we are making. You'll no doubt have already noticed that in the fragment we copied from Swagger, there was a string \{userId\} that we have replaced with my favorite dog's name, fluffy. Egeria has a number of ways of providing security, and passing in a userId is one of them. However, since we haven't configured and enabled this security, we could substitute fluffy with any string and it would have the same effect. OK, let's go ahead and press return and...

3. Whoops! We got an error message saying that we are using a self-signed SSL certificate (which we are) and that it can't validate the legitimacy of the server...ouch! Well, these are all valid concerns because we haven't acquired or created or configured SSL certificates for our deployment. However, that is a job for another day - to temporarily assuage our local security gods we just need to tell cURL to forego attempts at validating our certificate against an accepted certificate authority. We do this with the -k option like this:

We now get back the response we were expecting:

Egeria OMAG Server Platform (version 4.3)

While we just used the cURL command, we could have also used the Swagger site directly to try out this command. What you do is click on that little down arrow to the right of the description and it unfolds to show a form like this:

Now fill in the required information (in this case the userId) and press the Execute button:

And you will see the expected response:

Recap

In this recipe, we covered both how we can tailor how we start the Egeria OMAG server platform and how we can invoke services. We've started to get a taste for how security comes into play - but we've only scratched the surface there - Egeria has many different security and privacy mechanisms with both coarse and fine-grained access control, encryption, integration with external authentication and authorization systems and so on. As we progress through different recipes, security topics will be called out.

We also saw that Egeria provides a Swagger Site built right into the runtime. This means that we can always have a current view of what services we are running. If we upgrade to a new release with more services or if we tailor our distribution to exclude some capabilities, we can always look at the Swagger to see what's available to be enabled within an OMAG server. Of course, we can also disable the Swagger site for secure, production deployments.

In the next recipe we will introduce how to configure an OMAG server and activate it on the OMAG server platform..