Before I drift off into more complex topics, I thought I would get back to basics and level set on some ORDS fundamentals. I'll start off in this post by revisiting what ORDS is and then move onto describe some use cases where you can use it and wrap up with some REST basics and ORDS best practices. Following this post, I want to continue the back to basics theme and take you through some basic examples to help you better understand ORDS.
WHAT IS ORDS?
ORDS USE CASES
Exposing data RESTfully
The primary use case is to expose existing data as REST services. One area where I have seen this used extensively is exposing Oracle e-Business suite data as REST services. There are a vast array of use cases just here, think mobile applications for EBS users, facilitating connectivity to other middleware, facilitating MDM by making Customer or Item Master data easier to consume by other systems (and the list goes on).
Data Capture Machine
ORDS is a fast and light weight method of allowing you to capture data. Think IOT (Internet of Things). There is a vast amount of data coming at us and we need a way to easily capture it and store it using fast industry standard protocols. With ORDS, an Oracle NoSQL database and an AWS EC2 instance, you have a data capturing machine for very little cost.
On it's own ORDS is not capable of this, but given it runs on an Oracle database, why not take advantage of this and roll your own low cost integration middleware. After all, what is middleware, other than the ability to capture data (ORDS), transform it (PL/SQL and Oracle DB tables) and then pass it on to other systems (APEX_WEB_SERVICE). Most middleware tools use a database as a dehydration store anyway so why not make the database the heart of it all?
Facilitating Point to Point Integrations
Yes, I know we are in the 21st century and point to point integrations are frowned upon. Unless you have thousands (and thousands) of dollars to spend on complete middleware solutions (and the developers that come with them) you may not be able to afford that luxury. I can't tell you how many small to medium sized business I have come across that have an Oracle database and just need to be able to consolidate data from Salesforce and e-Business Suite so they can put together some consolidated reporting. In many cases the Oracle database, APEX and ORDS is the right sized solution for these companies. Even if these organizations grow in the future, they will already have REST services which are much easier to plug into middleware solutions such as Dell Boomi, Fusion Middleware and Mule.
The good news is that REST principals are not rocket science. Once you understand that you should be basing your services on resources (item, customer, sales order etc.) and allow the HTTP protocol to provide the action/verb (GET, POST, PUT, DELETE & PATCH) you are half way there.
Instead of me going into detail on my opinions on REST, I can save myself a lot of time and make a recommendation. When I started with REST I read a paper called 'Web API Design - Crafting Interfaces that Developers Love' by Brian Mulloy at APIGEE. Not only did it make sense to me but it also did not come with the 'though shalt do this' and 'though shalt do that doctrine' that you sometimes get. I try to follow these principals and they have worked well for me so far. You can get a copy of the paper from APIGEE's web site Direct Link. As an aside, APIGEE must know something about web services as Google just bought them Google to Aquire APIGEE.
ORDS BEST PRACTICES
Think About the URL
Given an ORDS URL is composed as follows:
- Remove 'ords' from your URL. You can do this by either renaming ORDS.war to something else e.g. API.war or using a routing rule in your web server.
- When you are enabling your schema for ORDS, think about how it will reflect in the web service URL. Just because you have a schema you want to ORDS enable called 'jonsscoolchema' does not mean you want the world to see that:
p_schema => 'JONSCOOLSCHEMA',
p_url_mapping_type => 'BASE_PATH',
p_url_mapping_pattern => 'erp',
p_auto_rest_auth => FALSE);
- If you want to version your APIs (which I recommend you do) then use the ORDS module as the version e.g. name your modules v1, v2 etc. That way when you introduce a new version, you can keep the old one around for a while until folks have moved to the shiny new one.
- looks a lot better (and more professional) than:
The ORDS team have given us a set of ORDS and OUATH PL/SQL APIs for defining, changing and deleting modules, handlers, parameters, clients etc. You can now construct SQL scripts to deploy your services making the process both quicker, more precise and less error prone. Use it!
Put Logic in PL/SQL Packages
Limit the logic in your ORDS handler to what you absolutely need to capture ORDS bind variables. Move as much of the web service logic as possible to PL/SQL packages. This includes getting http headers (think owa_util) and writing the response (think htp.p). This not only organizes your code better and makes it easier to reuse but it also makes it easier to deploy changes.
Think about how you want to authenticate your services before you start. For most B2B applications, OAUTH2 client credentials is sufficient. I have written a post on how to do this ORDS - Securing Services Using OAuth2 (2 Legged). You can also create your own authentication but doing this means you will need to write all your handlers as PL/SQL blocks, check authentication then construct responses for GET services manually (which is a bit of a pain).
Don't forget authorization, just because someone has access to your API does not mean they should see all the data. You can use the ORDS metadata to query the client and then decide what data that client should have access to.
Even though Brian talks about this in his paper, it bears repeating. If all goes well, your APIs are going to be used by lots (and lots) of people. Invest time up front in crafting clear error messages that give the developer information on what went wrong, how to fix the problem and a link to the documentation. As developers we often do the 'what went wrong' part but rarely provide the 'how to fix' it advise (and almost never the 'documentation'). Of course, you could shortcut this by just providing your cell number and email address in the error message and have the developer call you directly :)
Look out for my next post in the 'Back to Basics' Series in October.