REST APIs for Oracle Database: Postman vs Insomnia

I think every developer should get somewhat proficient with cURL, but. When you have more than 500 APIs to peruse for a single resource, having a GUI can be very handy.

And I don’t mean just any 500 or so REST APIs, I mean specifically the ones we publish in Oracle REST Data Services for managing and monitoring your Oracle Database. This feature is known as the ‘DBAPI’ – and it’s an optional feature of ORDS.

I introduced the DBAPI in ORDS feature here.

I talked about Data Pump via REST APIs here.

I talked about Cloning PDBs via REST APIs here.

Using Postman

First things first, you need to make sure ORDS has this feature enabled, and you need to get the JSON Open-API content.

http://.../ords/{user}/_/db-api/latest/metadata-catalog/openapi.json

If you can open that link from your ORDS deployment, then you know ORDS has enabled the DBAPI feature.

If you get 404’s, you’ll want to make sure it’s enabled in the ORDS config.

<entry key="database.api.enabled">true</entry>

Once you have the right URL, you can ask your trusty REST client to just ‘suck in the APIs…’

In Postman –

You’ll simply hit the ‘Import’ button. Don’t create a new Collection first, doing the Import will create a new Collection for you.

Click ‘Continue’ and then ‘Yes’ to a couple of default prompts, and you’ll be good to go.

You have a few categories of end points you can exercise.

One thing I really like about Postman, is that I can set my Authentication Scheme at a top-node level, and then have it propagated down for all my other calls.

When you’re setting this up in Postman, do it at the top level, put in the Creds, and then it ‘Save’

This wasn’t working for me until I hit the magic ‘Save’ button.

After doing this, everything worked just fine for me.

I also like that as I make requests, new tabs move across the top of the Client, just like I’d see in my favorite browser. I’ll need to close these, eventually.

Using Insomnia

It’s a pretty common workflow in Insomnia –

You don’t need to sign up for an account to use Insomnia, just download it.

Once I’ve pasted in the URI and hit ‘Fetch and Import’, I’ll see my new categories on the left hand side.

Environments in Insomnia allow me to define some things I want applied to all of my calls.

Let’s say for example that I want to be able to easily call the DBAPI from my local instance of ORDS/Oracle Database OR from my Always Free Autonomous Database in my Oracle Cloud Service.

The trick for making this happen is to create multiple ‘Environments.’

So I won’t have to mess with URIs on my calls between my different databases now, just pick the Environment I want to use.

However, one thing I do find annoying with Insomnia is that they don’t offer the ‘Inherit Auth from Parent’ option that Postman gives you. Oh well, I just have to remember to add/change those as I use them.

What about cURL?

Both clients have ‘code generators’ – so from my GUI HTTPS request to a pure cURL/code implementation. Using either will require some work to manipulate said code generated to get it to work, but Postman offers the most flexability.

You can pick from dozens of code options and for cURL you can set a dozen more specific preferences.

For Insomnia you get some options as well. I’m a big fan of HTTPie over cURL as it has a more human readable command syntax, and Insomnia supports that AND cURL!