As with all things APEX it is both easy and obtuse. The easy part is APEX while the obtuse part...well...that's Oracle. So here's the quickie primer on how to get a simple RESTful service up and running and to test it.
It actually is fairly simple, but if you don't know these basics then you'll get stumped for awhile and wind up searching the black hole that is Oracle's forum site.
Workspace Setup
As with all configurations on here, this is done using a *free* workspace set up at https://apex.oracle.com or use one you created prior. Create your workspace and make note of the Workspace name that you created. Below I'll use the convention of {Workspace} to indicate where you replace that with the name of your workspace (replacing the brackets too you idiot).
NOTE: These are shared across all the Oracle sites so trying to create a Workspace named Test probably isn't going to work. Make it something unique/interesting to you.
What's the #@#$! URL?!
As usual, Oracle has made this very easy, yet completely dropped the ball on one crucial bit of information. It is as if they are trying to explain how to make toast but never state to push the lever down on the toaster. You sit there for an hour waiting for toast to appear but the cold bread just lays there...
To set up a service (or view the included Oracle-provided example) start by logging into your workspace and at the top of the screen click on SQL Workshop and RESTful Services.
By default, you'll already have one service in there supplied by Oracle: oracle.example.hr.
You can click on it and browse around a bit and enjoy what "almost" seems like all the information you'd ever need for completing this, but the most obvious and necessary item will elude you: the URL for this RESTful service.
Now you might think the "Name" field is your answer (e.g. oracle.example.hr). Nope. Worthless. You might think the URI Prefix seems valuable (and you'd be right) but what else do you combine it with? Here's the answer to the question you shouldn't have to ask. The format is:
https://apex.oracle.com/pls/apex/{Workspace}/{URI Prefix} -or- {RESTful Service Module}/{URI Template}/
In the case of the Oracle-provided example, this becomes the following:
https://apex.oracle.com/pls/apex/{Workspace}/hr/employees/
Just replace the {Workspace} (as I indicated above) with the name of your own and the Oracle-provided example should work right out of the box. Why you could actually test it right now by using a RESTful client.
If you're using "some other" hosting for APEX, well you can also figure out your URI by clicking down into the sample application, clicking on the GET handler under employees (left-hand side of the screen) and then scrolling down to the veeeery bottom right where there is a button TEST.
Click that button and as a part of the JSON values returned you'll see the full URI embedded in there.
For example:
{"next":{"$ref":"https://apex.oracle.com/pls/apex/packetvac_test/hr/employees/?page=1"},"items":[{"uri":{"$ref":"https://apex.oracle.com/pls/apex/packetvac_test/hr/employees/7369"},"empno":7369,"ename":"SMITH"},{"uri":{"$ref":"https://apex.oracle.com/pls/apex/packetvac_test/hr/employees/7499"},"empno":7499,"ename":"ALLEN"},{"uri":{"$ref":"https://apex.oracle.com/pls/apex/packetvac_test/hr/employees/7521"},"empno":7521,"ename":"WARD"},{"uri":{"$ref":"https://apex.oracle.com/pls/apex/packetvac_test/hr/employees/7566"},"empno":7566,"ename":"JONES"},{"uri":{"$ref":"https://apex.oracle.com/pls/apex/packetvac_test/hr/employees/7654"},"empno":7654,"ename":"MARTIN"},{"uri":{"$ref":"https://apex.oracle.com/pls/apex/packetvac_test/hr/employees/7698"},"empno":7698,"ename":"BLAKE"},{"uri":{"$ref":"https://apex.oracle.com/pls/apex/packetvac_test/hr/employees/7782"},"empno":7782,"ename":"CLARK"}]}
Testing RESTful Services
Oracle's examples of course explain exactly how to test their RESTful Services using their own applications which is not at all what you'll actually be doing. It makes sense to them because they're Oracle and not you. YOU are thinking about using a RESTful Service because you're going to push/pull data from some other system. Duh.
For my test I used Jeroen's wonderful and simple test app at: https://resttesttest.com/
If you want to jump right to seeing how this works you can copy the URL from above and drop it into the Endpoint field on his page, hit the AJAX request button and you'll see the following
Note: My Workspace is named "packetvac_test" in this example so replace that with your own Workspace name. Have I said this enough yet?
When do I use /'s
Oracle's fields here are not clear on when/where you need to include the forward slash (/) on your items. So for example, if you go back and click on Oracle's-provided RESTful Service oracle.example.hr you will see on their first screen the following info:
What's not immediately obvious to everyone is that you have to put the /'s in certain fields so the complete URI is properly formatted. Sure you could leave these out and go rogue. Don't. Just...don't.
So again, back to the full example URI:
https://apex.oracle.com/pls/apex/{Workspace}/hr/employees/
In that scenario the hr/ component is actually defined on this page. So if you'd left off the slash on the URI Prefix field on the page/image above then the URI would actually be:
https://apex.oracle.com/pls/apex/{Workspace}/hremployees/
Just...don't. Please.
Anyway, if you click on one of the "GET" handlers on the left-hand side of the page/image above (e.g. under employees/) then you get the following page
Now *this* is the page where the neat stuff happens. Query code, types of formatting for the response, etc. But for now, all we care about are the fields at the top.
The field RESTful Service Module field is Oracle's way of reminding you that consistency is for chumps. This is just the exact same field as on the previous page, URI Prefix. Just bask in the joy of knowing that you aren't the only one who can't remember what they named something just one page prior.
The second field though is what we value here. The URI Template field is the final bit of our URI we needed. So again, note the / at the end of this value. This means that out of the box this URI works:
https://apex.oracle.com/pls/apex/{Workspace}/hr/employees/ (with slashie)
But this one doesn't:
https://apex.oracle.com/pls/apex/{Workspace}/hr/employees (no slashie)
So again, just remember that you need to put the /'s in these fields.
Next Steps
Making your own simple service is a bit more involved and is covered in lots of places online. I'd do it now but...lazy.
Oracle includes Handler methods for GET (as shown above), DELETE, POST and PUSH. But before you go messing with the other ones you definitely should examine how to make your own services secure. For example the Origins Allowed and the Required Privilege fields are crucial.
But at least now you know that you can fairly quickly do a test to see if you can connect to Oracle APEX session and issue a RESTful service request before you start digging into the hard stuff.
But at least now you know that you can fairly quickly do a test to see if you can connect to Oracle APEX session and issue a RESTful service request before you start digging into the hard stuff.
