Oracle REST Data Services (ORDS) : Database APIs – First Steps

In my never ending quest for automation, I finally got round to looking at the Oracle REST Data Services (ORDS) Database APIs.

These have been around for some time, but I was testing them for the first time using ORDS version 20.2, so I was basing my tests on that version of the documentation, and more importantly version 20 of the APIs.

The are several sets of APIs, and they don’t have the same dependencies or authentication methods. It’s not that big a deal once you know what’s going on, but it confused the hell out of me for a while, and the documentation doesn’t give you much of a steer for some of this.

PDB Lifecycle Management

My first tests were of the PDB Lifecycle Management endpoints. I enable all the relevant features in my normal installation, but there was one big road block. I always install ORDS in the PDB, and this feature only works if ORDS is installed in the root container. This makes sense as the management of PDBs is done at the root container level, but I prefer not to put anything in the root container if I can help it. I uninstalled and reinstalled ORDS so I could give it a go. This resulted in this article.

The PDB Lifecycle Management functionality seemed better suited to a self-contained article, as it is only available from a CDB installation, has its own authentication setup and only has a small number of endpoints. The available APIs are kind-of basic, but they could still be useful. It will be interesting to see if this expands to fit all the possible requirements for a PDB, which are now pretty large. I suspect not.

Most of the other stuff

Next up was “most of the other stuff”. There are too many endpoints to go into any level of detail in a single article, so I figured this should focus on the setup to use most of the other endpoints.

There are two methods of authentication discussed. The default administrator approach, which is good because it hides the database credentials from the user making the API calls. Instead they use application server credentials mapped to the “System Administrator” role. This is similar to that used by the PDB Lifecycle Management feature, except that uses the “SQL Administrator” role, and the ORDS properties are different..

The other approach is to use an ORDS enabled schema. This will be very familiar to people already using ORDS, but it comes with one big disadvantage compared to the previous method. For this functionality you have to expose the database credentials of the ORDS enabled schema to the person calling the API. Normally we would not expose these, instead using another form of authentication (Basic, OAUTH2 etc.) to allow the user to gain access. Even then the ORDS enabled schema would be a weak user that only has access to the specific objects we want it to interact with, but in this case it’s a DBA user, so it makes me nervous. Using the default administrator method the caller is constrained to some extent by the APIs, but with the database credentials they have everything if they have direct access to the database server. It’s probably insignificant when you consider the amount of damage someone could do with the APIs alone, but I feel myself wincing a little when putting DBA credentials into a HTTPS call.

For me as a DBA/Developer I would see myself as the person using these APIs to develop something, whether that was an automation, or an application. If this were to be handed over to a developer to do the work, these security questions may be a much bigger issue.

Having read that, you are probably thinking, just use the default administrator method then. I would, only some APIs don’t work with that method. Some seem to only work with the ORDS enabled schema method for authentication, while others only work with the default administrator method. What’s more, I don’t see any reference to this in the documentation. The API doc doesn’t even mention the default administrator approach, and the setup doc doesn’t mention the limitations on any of the approaches except the PDB lifecycle management. As a result, I think you will need to use a mix of the authentication methods if you plan to use a variety of functionality.

The good thing is they can all live side-by-side. At one point I was testing with a CDB installation of ORDS with credentials for PDB Lifecycle Management, default administrator and ORDS enabled schema authentication all configured at the same time. No problem. It’s just confusing when endpoints fail and you have to “trial and error” your way through them. It would be nice if there was a grid of which groups of endpoints need which type of authentication.

Now I am a noob, so maybe I’ve missed the point here, but I spent a long time trying out variations, and this seems like the way it is. If someone can educate me about why I am wrong I will willingly amend the articles, and this blog post. ๐Ÿ™‚

Thoughts and what next?

At this point I’ve just been finding my feet, and I’m not sure what I will do next. There are some endpoints that interest me, so I might do separate articles on those, and refer back to the setup in the above articles. Then again, it may feel like just regurgitating the API documentation, so I may not. It’s worth taking a look at the available endpoints, broken down into these main sections.

  • Clusterware CLIs
  • Data Dictionary
  • Environment
  • Fleet Patching and Provisioning
  • General
  • Monitoring
  • Performance
  • Pluggable Database Lifecycle Management

Some will require additional setup, but many will not.

From the look of it, the vast majority of the endpoints are for reporting purposes. There are far fewer that actually allow you to manipulate the contents of the database. You can always write your own services for that, or use REST Enabled SQL to do it I guess. The question will be, can I get enough value out of these APIs as they stand to warrant the investment in time? I’m not sure at this point.

Cheers

Tim…

PS. If you were watching my twitter feed over the weekend and wondered what bit of tech I gave up on. It was this. I’m very stubborn though, so I came back…

Video : Simple Oracle Document Access (SODA) for REST

In today’s video we’ll give a demonstration of Simple Oracle Document Access (SODA) for REST. This is a feature of Oracle REST Data Services (ORDS).

This video is based on the following article.

There are some other resources that might come in handy.

The star of today’s video is the son of Rodrigo Mufalani. Rodrigo is a fellow Oracle ACE and you can check out Rodrigo’s blog here.

Cheers

Tim…

Video : Oracle REST Data Services (ORDS) : REST Enabled SQL

Today’s video is a run through the REST Enabled SQL functionality in Oracle REST Data Services (ORDS).

I wasn’t originally planning on doing this video yet, but the subject of REST Enabled SQL came up a couple of times in the last few days, so I thought I would alter my schedule.

This video is based on the following article, where you can find a lot more examples than are present in the video.

There is a lot more information about ORDS generally in these articles.

The star of today’s video is Emrah Mete, who finished up with an crazy grin. ๐Ÿ™‚

Cheers

Tim…

Video : Oracle REST Data Services (ORDS) : Create Basic RESTful Web Services Using PL/SQL

Today’s video is a brief run through creating RESTful web services using Oracle REST Data Services (ORDS) and PL/SQL.

This is based on the following article, but the article has a load more examples and variations compared to the video.

I don’t mention handling complex payloads or status information, but you can find that here.

You can see all my other ORDS related content here.

The star of today’s video is Alan Arentsen. Finding a clip without him giggling or laughing was kind-of tough… ๐Ÿ™‚

Cheers

Tim…

ORDS, SQLcl, SQL Developer 19.2 (Vagrant and Docker Builds)

The folks at Oracle dropped some new presents for us today, including version 19.2 of the following.

I’ve updated my Vagrant builds and ORDS Docker builds with the new versions and everything seems to be working fine so far.

Tomorrow I’ll probably try out some of our development ORDS containers with these releases and see how they work out. They are similar to this build, so I’m sure they will be fine…

Cheers

Tim…

Update: I rolled ORDS 19.2 out to all our Dev/Test environments this morning. We run them all on Docker, so it was really quick and easy. ๐Ÿ™‚

Oracle REST Data Services (ORDS) 18.4

It’s hardly news, as Oracle REST Data Services (ORDS) 18.4 has been out for a while, but I thought I would mention a couple of things related to it.

First off, we’ve upgraded (almost) all of our ORDS installations to 18.4 at work. I say almost because we’ve got a couple of 11.2 databases that don’t work consistently with anything newer that ORDS 3.0.12, so they aren’t being touched until we’ve upgraded the databases. This is how I typically do the upgrades.

Regarding my GitHub stuff.

  • Vagrant : My 18c, APEX, ORDS and Tomcat installation uses ORDS 18.4 and Java 11.0.2.
  • Docker : My ORDS build has been upgraded to 18.4 and Java 11.0.2.

We’ve not had any drama related to this. ๐Ÿ™‚

Cheers

Tim…

Chrome 68, HTTPS , Let’s Encrypt and ORDS

In February Google released a post about Chrome 68, due for release in July, which will increase the pressure to adopt HTTPS for all websites because of this behaviour change.

Basically HTTP sites will be marked as insecure, rather than just getting the (i) symbol.

Recently I’ve seen a bunch of sponsored posts talking about this in an attempt to sell certificates. GoDaddy are pushing the advertising hard. I just wanted to remind people there is a free alternative called Let’s Encrypt you might want to consider.

Let’s Encrypt

I’ve been using HTTPS for a few years now, but over a year ago I switched to using the free Let’s Encrypt service to get my certificates and so far I’ve had no problems. I wrote about this in a blog post here. That links to this article about using CertBot to automate the certificate renewal, which includes the Apache HTTP Server config.

The article also links to this article about configuring HTTPS for Tomcat, which includes an example of using a Let’s Encrypt certificate.

I always run Oracle REST Data Services (ORDS) under Tomcat, so this is how I HTTPS enable ORDS. If you would prefer to run ORDS in standalone mode, but still want to use a real certificate Kris Rice has your back with this article.

Of course, you shouldn’t be having direct traffic to Tomcat servers or standalone ORDS services you care about. They should be sitting behind some form of reverse proxy, or a load balancer acting as a reverse proxy, which is performing the SSL termination. In my company, we have the real certificates on the load balancers, which perform the SSL termination, then re-encrypt to speak to the services below them.

Thoughts

In general I think the push towards HTTPS is a good thing, but I do have a few reservations.

  • There are plenty of sites, like my own, that don’t really do anything that requires encrypted connections. You are just there to read publicly available stuff. Marking them as insecure seems a little stupid to me. Update: As pointed out in the comments, it does make it harder for people to intercept and change the information during transit.
  • A bigger beef is the fact that anything with a valid HTTPS certificate is marked as “Secure”. If you work in IT you understand this just means the connection is secure, but what does it mean to other people? I could understand it if some people thought it meant it was a safe website to visit, when it means nothing of the sort. If HTTPS is the new “normal”, I think the browser should stop marking it as secure, and only flag when it is insecure. Update: It seems this is going to change (here). Thanks to Gary for pointing this out.
  • It worries me that Google can make this decision and the rest of the world has to jump. This all started when they began to alter index ranking based on the presence of HTTPS, which is why I first enabled HTTPS on my website about 4-5 years ago I think. Now the Chrome market share of about 60% is such that they can make big changes like this without having to get buy in from the rest of the world. The motives are good, but I don’t like it.
  • I’m not saying you shouldn’t pay for certificates. My company still does. I’m just saying you have a choice, especially if it is something that you do for fun like this website. In this case the free option is always the good one. ๐Ÿ™‚

Happy encrypting…

Cheers

Tim…

Oracle REST Data Services (ORDS) 3.0.10 : Going down the rabbit hole!

Oracle REST Data Services (ORDS)ย version 3.0.10 was released last week. In addition to a bunch of bug fixes it was the first release to include the Auto PL/SQL feature.

Auto PL/SQL is similar to the AutoREST feature available for tables and views, but it allows you to enable PL/SQL objects for Remote Procedure Call (RPC) over HTTP(S). At this point you might be asking yourself what the difference is between REST and RPC over HTTP and I explain that here. Regardless of whether it is REST or not, it’s a nice convenience feature that I’m sure some people will find useful.

Over the weekend I went full on down the rabbit hole, which resulted in this article.

There are a number of issues with the current release and the docs for it, all of which have been fed back to the relevant parties, but on the whole I think it’s a neat first step.

My preference is still to define conventional ORDS RESTful web servicesย rather than use this feature, but Auto PL/SQL may be just what some others are looking for and it’s always good to have options! ๐Ÿ™‚

As far as the 3.0.10 release generally, I upgraded 4 non-prod installations to this release, all actively used for fronting APEX and RESTful web services and nobody has had a problem yet. ๐Ÿ™‚

If you are yet to experience the joys of ORDS you can read the articles I’ve written about it here, as well as an introduction to JSON here.

Cheers

Tim…