 | 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 allows you to capture or expose data in an Oracle Database (relational or NoSQL) using the ubiquitous REST protocol. It is delivered as a Java application (war file) that can run standalone or within a J2EE container (think Apache Tomcat, GlassFish, WebLogic). Used in conjunction with the APEX5 web service and JSON parsing PL/SQL APIs, it can turn your Oracle database into a fully functional integration hub. I won't regurgitate the product data sheet, but other goodies that come with ORDS include OAUTH2 authentication, automatic parsing of SQL into JSON, automatic handling for HATEOAS (Hypermedia as the Engine of Application State), automatic paging for GET services and read consistency to name but a few.
ORDS Architecture
ORDS USE CASES
Many customers have asked me "when should I use ORDS"? As is typical for someone who was a consultant for 18 years, my answer is usually "it depends" and in this case it really does. The best way I can describe it is to walk through some use cases and illustrate why ORDS is appropriate.
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.
Integration MiddleWare
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.
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.
Integration MiddleWare
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.
REST PRINCIPALS
Before diving into ORDS and exposing data left and right (which is both tempting and very easy to do), I strongly suggest you get a handle on REST principals first. It is very easy to abuse REST and create services like getCustomer or updateItem and pay no heed to versioning. Coming from a database programming background, I had to check myself constantly at the beginning.
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.
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
Whilst by no means comprehensive, I want to leave you with some thoughts on best practices for implementing great APIs with ORDS.
Think About the URL
Given an ORDS URL is composed as follows:
https://example.com/<warfile>/<schemaname>/<module>/<service>
Deployment
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.
Authentication
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).
Authorization
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.
Error Messages
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 :)
Think About the URL
Given an ORDS URL is composed as follows:
https://example.com/<warfile>/<schemaname>/<module>/<service>
- 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:
- BEGIN
ORDS.ENABLE_SCHEMA(
p_schema => 'JONSCOOLSCHEMA',
p_url_mapping_type => 'BASE_PATH',
p_url_mapping_pattern => 'erp',
p_auto_rest_auth => FALSE);
END;
- BEGIN
- 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.
- Generally:
- http://example.com:8080/api/erp/v1/customer/1234
- looks a lot better (and more professional) than:
- http://example.com:8080/ords/erp/customer/getCustomer?customerId=100
- http://example.com:8080/api/erp/v1/customer/1234
Deployment
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.
Authentication
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).
Authorization
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.
Error Messages
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 :)
Conclusion
For someone who said they were going to leave the advise to someone else, I just gave you a lot of it. Seriously though, I am a big fan of ORDS and think it has enormous (mostly untapped) potential.
Look out for my next post in the 'Back to Basics' Series in October.
Look out for my next post in the 'Back to Basics' Series in October.
RSS Feed