Since re-joining Oracle, my first major project has been to work on better integration of APEX and ORDS when it comes to the definition of RESTful Services.
APEX has long had the ability to define and serve RESTful Services on its own. These have been managed via a section of the SQL Workshop known as the RESTful Services Console. These services being separate from those defined as part of ORDS has caused some confusion over the years.
If you define a service in APEX, why can’t you see it in ORDS, and likewise if you define a service in ORDS (using either SQL-Developer or the PL/SQL APIs) why can’t you see it in APEX. The answer is very simple – their definitions are stored in two separate repositories, neither knowing about the other.
So, the decision has been made that ORDS shall be the “way forward” in terms of RESTful service definitions. What this means for those who have created services in APEX is that you’ll need to migrate those definitions into the ORDS metadata repository, as the use of APEX RESTful Service will eventually be deprecated . Fear not, this is easier than you might think and actually gives you better control over security in the long run.
The rest of this post will give you an overview of the upcoming changes to the REST Services Console in forthcoming version of APEX. Please note that the screenshots I’m sharing are of pre-production software and the final release may change from what you’re seeing here.
What you see will depend on what you have
There are basically three scenarios that will alter what you see when you navigate to the RESTful Services section of APEX, and they depend on a couple of things:
- What version of ORDS are you running?
- Does your workspace already have APEX based RESTful Services defined?
The scenarios are as follows:
– You’re running an old (pre 17.4.1) version of ORDS
In this scenario you’ll be taken directly to the current APEX based RESTful services console just as you were before. You’ll be shown a warning message stating you have not met the minimum ORDS version that allows you to use the ORDS RESTful Services console. You’ll be able to continue creating and maintaining APEX Based RESTful services, but should start thinking about upgrading ORDS as soon as appropriate.
– You’re running ORDS 17.4.1 or above and have APEX Based REST services defined in your workspace
In this scenario you’ll be taken to an options menu that will allow you to navigate to a read-only version of the APEX RESTful Services console or to the new ORDS RESTful Services console.
Clicking on the APEX Based RESTful Services option will take you to the familiar console you’re used to seeing with two major differences. First, all service definitions will be read-only and there will be a message at the top of the screen notifying you of such. Second, there is a new button that allows you to migrate all of your APEX Based RESTful service definitions from the current workspace into the ORDS repository.
Clicking the ORDS Based RESTful Services option from the previous screen will take you to the full ORDS console where you will be able to create an maintain service definitions that will be stored in the ORDS Metadata tables.
– You’re running ORDS 17.4.1 or above and have no APEX Based REST services defined in your workspace
Under this scenario you will be taken directly to the ORDS RESTful Services console and will no longer have access to APEX Based RESTful Services.
The ORDS RESTful Services Console
When accessing the ORDS RESTful Services console for the first time, it is likely that your schema won’t be registered with ORDS. If this is true, you’ll be presented with a warning and a button that will allow registration.
Clicking the button will display a dialog with options for enabling ORDS REST for the schema.
Enabling the schema will then allow you full access to create and manage ORDS Based RESTful Services from within APEX. In the dashboard example below you can see that I chose to install the Sample HR service, set my schema alias to dag_ords and chose not to require authorization for access to the REST Metadata for the schema.
From here you’ll be able to create and maintain RESTful services, the definitions of which will be stored fully within the ORDS metadata repository. What this means is that you’ll be able to see those services in SQL-Developer and in the ORDS metadata views from the underlying schema. As an example, below are some screenshots of one small section of the sample HR service.
ORDS Module Definition Page
ORDS Template Definition Page
ORDS Handler Definition Page
New things to look out for
By moving to the new ORDS Based RESTful Services you get many benefits out of the box including the following:
- REST Services in all associated schemas – When using APEX Based REST, services were created against the first schema assigned to the workspace and only that schema. There was no way to create services for other schemas assigned to the workspace. When using ORDS Based REST, you’re able to manage services in any schema assigned to the workspace. Each is treated separately and each has it’s own Schema Alias that forms part of the URL used to access RESTful Services within that schema.
- Swagger Doc – ORDS provides the ability to generate Swagger documentation for any module defined within its metadata repository and now this functionality has now been integrated in to APEX. There is a new instance level setting allowing administrators to specify the URL of a Swagger UI server. If the URL is filled in, the Generate Swagger Doc button on the Module Definition page will open a new window and display the output from the Swagger UI server. If the URL is left blank, clicking the button will open a new window and generate the raw Swagger JSON that can be cut and pasted into a Swagger UI server.
- Easily see which services are protected – On the Module report page and in the Templates report on the Module Definition page you can see a visual indication of whether an all or part of a module, or an individual template is protected by an ORDS Privilege. This helps make sure services aren’t accidentally left open to the world.
Things Coming in Future Releases
No matter how hard you try, you can’t get everything you want into the first release of anything. There were a few major things that we wanted to get in but that will have to wait until a future release.
- OAUTH Client Management – Currently you must either use the screens built in to the ORDS engine, or the PL/SQL APIs to create OAUTH Clients. The plan is to create a set of screens within APEX to allow OAUTH client management as well. This way you will be able to manage both Services and their Security in one place.
- REST Enabled Object Management – Right now there are two ways to REST Enable database objects; Via SQL-Developer or via the PL/SQL APIs. The goal is to provide an interface to do this within APEX as well. One obvious place to REST enable a single object would be in the Object Browser, but I can also see that it would be useful to have a wizard that allowed you to pick multiple database objects to REST enable.
- Guided Tour – Knowing that not everyone is familiar with creating REST services, is very probably that some may not know where to start. Therefore we’d love to use something like Hopscotch to provide guided tours of the interface and walk you through how to create and protect your first web services. This is a larger undertaking than it may seem as bundling Hopscotch into APEX will mean quite a bit of work. Not to mention writing and testing the tour scripts.
I know this has been a pretty high level overview, but to go into more detail would basically be to repeat what’s going to be in the documentation.
Again, don’t take any of this as a promise of things to come. Until the software hits GA, it’s all smoke and mirrors.