While SQL may appear on just about every list of skills an IT professional today should strive to attain, SQL isn't always the best way to interact with your data.

Source: insights.dice.com

Using SQL assumes you actually have access to a database...which would generally indicate you have an account on said database.

I'm sorry, but for many application developers, there's no need to give you the keys to my castle.

Craig is a great networker of database professionals and a good follow

I share this tweet, even being tongue-in-cheek, as it can speak to the frustration I've seen developers have when trying to work directly with a database.

It's been said a few times that database administrators have sometimes been seen as less than friendly. Not to cast aspersions on an entire class of IT professional, but we should also remember a DBA's #1 task is to...

PROTECT THE DATA

One of the best way to 'protect the data' is to limit access to it. And when access is given, always with the least amount of access required.

Sometimes that means having to say mean things, like 'No.' But instead of saying just 'no,' great DBAs will say 'No, however I can get you what you need via X.'

Enter the REST APIs

What if instead of connecting to a database, you could simply call out via HTTPS to 'GET' the data you need to work with in your application?

This would have a few immediate benefits...

1. No need to configure or manage database clients, drivers, libraries
2. No need to acquire database credentials
3. No need to create and maintain stateful, connections to a database
4. No need to learn SQL - at least in this use case
5. No need to even realize there's an actual database in the application's 'universe'

Middleware/Mid-Tiers

There is a client and a database in our universe. But this communication, these connections, this setup, it's all handled via an additional party.

This 'party' does all the 'icky' database stuff for us, it does all the SQL, and database things. It ALSO speaks HTTPS and supports what we know and and rely on for REST APIs.

Oracle has a Java application running in this mid-tier that talks both HTTPS and SQL.

Your code uses HTTPS to communicate wit the mid-tier. The mid-tier uses SQL to talk to the database. The results of said SQL, are communicated back down to the client via the HTTPS response, using {JSON}.

Oracle REST Data Services is our 'additional party' doing the database work FOR us.

Oracle REST Data Services Product Page and Resources Your IT administrator or maybe even your database admin will assist in setting up this mid-tier. The program (Java in this case), will have a connection pool it uses to satisfy your HTTPS requests, but running the SQL and other database commands for you.

It also has the 'brains' to take a SQL result set or standard output from the database, and send back to you a JSON document with appropriate 200, 201, or gosh forbid 404 status codes.

How the 'brains' stuff actually works

Let's look at the definition of an API first, say, a GET endpoint

Give me a list of our employees.

Database Universe, that translates roughly to

select * from employees

REST API/HTTPS Universe that translates roughly to

GET employees/

When we define our REST API, we minimally supply a MODULE, a TEMPLATE, a HANDLER, and required PRIVILEGE to be authorized.

Modules allow you to organize your APIs.

Templates are the abstraction of your database resources to an HTTPS Uniform Resource Identifier (URI.)

Handler is the HTTP Verb (GET, PUT, POST, DELETE, & HEAD)

You can have different SQL for each HTTPS verb.

A REST API as it's defined by our mid-tier application serving them up.

And if I ask for this resource in my browser...

Those rows in the tables from our SQL query results, have been turned into JSON.

That's not very RESTy..or RESTful, Jeff

HATEOAS (Hypermedia as the Engine of Application State) is a constraint of the REST application architecture. HATEOAS keeps the REST style architecture unique from most other network application architectures.

The term “hypermedia” refers to any content that contains links to other forms of media such as images, movies, and text. Citation

I have nightmares where I'm on stage giving a talk on REST and someone asks me to pronounce 'HATEOAS.'

If our Collection were RESTful , we'd have links to those individual resources, or in our case, individual employees.

So let's build that API now.

MODULE I already have a module for my employees endpoints, and I'm happy to stay there. So what I need to do is add a new TEMPLATE.

TEMPLATE I want to pull up an employee via their Primary Key value, which is EMPLOYEES.EMPLOYEE_ID. The template for that would be something like:

employees/:id

The collection template is 'employees/' - we're just tacking on the :id to that.

OK, we want to pull up a record, that's just going to be a simple GET. So we'll use the built-in REST IDE to add a GET handler to our Module.Template definition:

All in one go, I can say, hey this is a single item, and here's the SQL statement to run when someone accesses the API.

The mid-tier is smart enough to know how to parse the HTTPS Request URI and see the pattern, and send the value after employees/ to the SQL bind variable, ':id'

So for example if do a GET on employees/101 - I get the record in the EMPLOYEES table where EMPLOYEE_ID = 101.

That's great, but how do we add the links to the main collection API, so that our apps can navigate from doing a GET on employees/ to a GET on one of the resulting collection items?

Adding Links

Let's go back to our main collection GET Handler.

We're going to supply the list of columns vs using '*' in our SELECT. AND, we're going to use an Oracle REST API 'trick' - adding a column alias that starts with a "$."

This trick tells our REST API that the column should be treated as a resource link.

*Our resource link item is going to be called "employee record"

Now if we call our GET on employees/ -

Each item in the collection includes a related link to the employees/:id and associated template

Paging

The collection results...what if you had more than 100,000 employees like we have here at Oracle? Well, you probably don't want to see all 100,000 at once on your iPhone.

So our REST API technology is smart enough to automatically break up the results in pages, default size of 25.

We actually grab 27 or 28 records at a time. If we have more than 25 come back, we know there's another page to fetch. If there's 25 or less, then we know that "hasMore" is false, and you won't get a "next" link at the end of the JSON document.

See also: How Paging Works with Oracle REST Data Services.

There's more, much more where this came from

You can do INSERTs, UPDATEs, and DELETEs in SQL. You can JOIN multiple tables together. You can use VIEWs instead of TABLEs. You can even run Oracle PL/SQL...and all of this can be leveraged by your Oracle REST APIs.

My curated list of 'How do I...with ORDS' resources.