REST APIs to manage your REST APIs in ORDS 23.1

The primary feature for Oracle REST Data Services (ORDS) is serving up REST APIs for your Oracle Database.

Those include:

REST APIs for the data, code, and objects in your Oracle schema
REST APIs for the database itself

What I’m going to talk about today is the point where those two topics come together.

What does this mean?

It means that we have REST APIs you can use to manage your schema based REST APIs!

If we pull up the OpenAPI Spec in Swagger Tools, I can see in version 23.1 of the DBAPI, we have a new section labeled, ‘ORDS REST Services.’

61 Endpoints, give or take…

Wait, how did I pull those up?

Well you can cheat and go straight to the Docs. Or, if you have an install of ORDS with the DBAPI enabled, you can go to a URL that looks like this:

http://.../ords/jefe/_/db-api/stable/metadata-catalog/openapi.json

‘jefe’ is the Alias for my REST Enabled Schema user. That user will be used to AUTH my requests to those end points.

Taking a test drive

Tell me about my schema

In terms of ORDS, what’s going on?

http://.../ords/jefe/_/db-api/latest/ords/rest/overview/schema

This is a GET request, so I can call it from my browser.

The JEFE schema is aliased as ‘jefe’ and the schema is ‘Enabled’ for ORDS.

Let’s Create a new REST Module

Let’s look at my list of modules from say, SQL Developer (Desktop), and see what it looks like.

I mean, it should have a default pagesize of 18, and ZERO templates, handlers, or parameters.

There it is!

And it’s a ‘naked’ module. It exists, but there are no APIs defined in it.

Now why do you suppose we built REST APIs to manage our REST APIs, Clients, Privileges, and Roles?

We’re using these REST APIs to power the REST Workshop in SQL Developer Web!

So when I click ‘Create Module’ it’s going a POST to the ords/…/modules/ URI.

Pretty cool, right?

It’s gets even cooler, because we drink our own champagne, so to speak.

In the REST Workshop, and all over SQL Developer Web we have a ‘Show Code’ toggle. This allows us to show you HOW we are going to do the work for you.

In the prior POST, in my payload I had an attribute labeled, “run_mode” set to NULL.

What is run mode??

Let’s look at the ORDS Docs.

What happens if I instead do a POST with that set to ‘codePreview?’

Let’s find out!

Note that the Status is 200 vs 201? The module wasn’t actually created.

The response is just some text.

Does this look familiar?

So we enhanced our APIs to be able to instead generate the PLSQL API calls that ORDS would use to do the work shown in the REST web screens.