Most folks reading this know that Oracle REST Data Services (ORDS) is a great way to bring your aging Oracle Database systems into the world of REST services. ORDS provides a fully functional, robust and secure REST infrastructure that you can have up and running in hours. What may not be as obvious, is that because ORDS services are standard REST end points, we can utilize 'standard' tools for documenting them.

Like many of you (I suspect) I used to document my ORDS REST services using MS Excel or MS Word. Whilst better than not documenting them at all, I figured there had to be a better way. I am here to tell you that there is a better way and that is to use REST specification standards such as RAML, Swagger or API Blueprint. The standard itself is one thing but it is the tools that are born from these standards that really make the difference for me.

Not only can we create very nice documentation using simple markup, but we can also share it with our consumers at design time. In some cases, we can even auto-generate mock end points from the markup without writing any code. These end points can be called by our customer's client applications during design. All of this facilitates Spec Driven Development, which is a game changer in the API design world. You can now collaborate fully with your consumers before a single line of code has been developed.

I am not going to try and make this post about how to learn and use RAML (many have gone there already). The goal here is to open the hearts and minds of the ORDS to community to using a standard like RAML for their next project.

To be honest, I chose RAML based on reading the book Undisturbed REST by Michael Stowe. If you have not already read the book, then you should. The book offers a pragmatic look into REST concepts and design principals with some real world insights to boot.

BTW, looking under the hood at https://apicatalog.oraclecloud.com, it would appear Oracle is using Swagger.

For business to business services; we have traditionally written a design document (in Word or Excel), reviewed it with our consumers and signed in blood that we will adhere to the 'contract' which the design represents. We then went our separate ways and built our service or client app. The problem arose when we met again after two weeks to do a real live test of the service. Only then did we realize how different our understanding of the design was and that we have a lot more work to do.

With a Spec driven design approach we focus on iterating together until we get a solid specification. At this point, you may ask "how is that different?". The main difference is in the tools. With tools like Mulesoft's Anypoint Platform and RAML, we can:

• Document the service in RAML and have the tool automatically generate HTML based documentation.
• Provide a web based portal to your developer community or consumers so they can see the service evolve. When you change the RAML, they immediately see the documentation reflect this change.
• Finally, (and this is the big one for me), the tool can generate mock end points (based on your RAML specification) which our consumers can call. This is without having to write a line of code.

In this model, not only do our consumers get to see live documentation but they can also call the mock end points and get real JSON back. This means they can incorporate these mock services in their new prototype UI and show it to their end users to get feedback. You now can get real feedback on your API before you have written a line of code.
Both sides can now start development at maximum velocity with the confidence that they have a good understanding.
Check out Mike Stowe's Blog for properties and advantages of Spec Driven Development.

What is RAML? From raml.org:
"RESTful API Modeling Language (RAML) makes it easy to manage the whole API lifecycle from design to sharing. It's concise - you only write what you need to define - and reusable. It is machine readable API design that is actually human friendly."

My favorite aspects of RAML are:

• Easy to understand markup
• Generates clean, easy to understand documentation
• Tools available to auto-generate mock end points
• Great re-usability with 'traits', 'libraries' and 'data types'. This means if you use a certain type of security across all your APIs, you can define it once and then just reference it in all your services. Similarly, if you have a standard definition for a sales order, you can define it in a data type and then include that data type in your other services

​ Blogs & Books

• Blog from Mike Stowe What is Spec Driven Development
• Blogs from RAML.ORG
• Undisturbed REST eBook

Tools

• Mulesoft - Anypoint Platform (https://anypoint.mulesoft.com)
  • Web based platform
  • Design REST API's Using RAML
  • Live generation of documentation (as you type)
  • Developer Portal available to share APIs
  • Auto generation of mock end points
• Mulesoft - API Workbench (http://apiworkbench.com/)
  • Atom Package
  • Create RAML to design REST APIs off-line
• Other RAML Tools:
  • http://raml.org/projects/projects

Tutorials

• RAML 100 Tutorial (http://raml.org/developers/raml-100-tutorial)
  • Learn the Basics
• RAML 200 Tutorial (http://raml.org/developers/raml-200-tutorial)
  • Design a sample service End to End using RAML
• Mulesoft - Undisturbed REST Workshop
  • 10 part video series based on the book Undisturbed REST

Example Specifications

• https://github.com/raml-apis
  • Real World RAML specifications Created by other companies (such as Instagram, Spotify, Google, Slack etc.) 

Oracle ORDS can host REST services just like any other tool such. Given that, we should be using industry standard tools to design our ORDS REST services. Hopefully you can see that using a standard like RAML is not just about using standards. It actually makes your life easier and more importantly it improves the life of the people who are going to consume your services. Using a combination of RAML, the associated tools and a Spec Driven Development approach with your next Oracle ORDS project will pay dividends.

Installing GlassFish and deploying Oracle ORDS is well documented and fairly routine these days. It's really just a couple of downloads some unzipping, enter a few commands and you are pretty much there. That get's you a functional install but does not get you a production ready setup able to stand up to the rigors of a high volume and highly available production system.










​How far short of production ready is it? It may surprise you to know that the default installs will leave you with the following shortcomings:

• When ORDS starts up, only 1 JDBC connection will be available incurring an overhead to start up other connections as users access ORDS
• A maximum of 10 users can be accessing APEX at the same time
• GlassFish will be running in development mode (which incurs an overhead in checking to see if code has changed)
• None of your static files will be cached
• If you have more than 1 CPU, you will not be taking advantage of it
• GlassFish will only assign .5GB ram to Oracle ORDS, even if you have more available
• Logging will be set to Info, adding a significant burden to GlassFish
• ORDS will not log to the GlassFish log files
• You are in danger of timing out on large file uploads

BTW, the list is pretty much the same for Tomcat. In this post, I'll point you in the right direction to get Oracle ORDS and GlassFish ready for production.

Of course every use case is different. In my example I am going to assume an actively used system with 250 users and an anticipated peak load of 50 users running in parallel. Remember, because of the stateless nature of APEX and ORDS, your database connection is returned to the pool as soon as your page renders (or your web-service returns a response). That means in our example we are assuming that 50 users could be clicking on a button at exactly the same time requiring all 50 connections (that is a lot). We are assuming a normal load of 20 concurrently active users. I am going to assume we have a dedicated web server running ORDS and GlassFish with 4GB RAM and 1 Quadcore CPU.

You may have noticed the warning message when starting ORDS with default settings. There are four settings in the default.xml fle that need to be adjusted from the out of the box settings:

• jdbc.InitialLimit (the number of DB connections that will be created when the server is started) & jdbc.MinLimit (minimum number of DB connections that will be kept alive at idle, or low water mark)
  • The default for these settings are 3 and 1 respectively
  • There is an overhead in ORDS establishing a new connection. In view of this we would want to set these values to our anticipated normal load.
  • In our example this would be 20.
  • I can't think of any reason these two values should be different.
• jdbc.MaxLimit (maximum number of DB connections that can be active)
  • The default value is 10
  • This is the high water mark. As connections close through inactivity the number of open connections will idle down to jdbc.MinLimit
  • This should be set to the maximum anticipated concurrent load which in our case is 50
• jdbc.MaxStatementsLimit (the maximum number of SQL statements to cache for each connection)
  • The default value is 10.
  • If we have available memory, we should up this to 20.
  • Note: If all our connections are busy this would be 50 connections * 20 cached SQL statements * (let's say average SQL statement size is 250 bytes) = 244K

There is a lot more to do on the GlassFish side. For each of the configurations, I will mention the human readable option name from the GlassFish Admin Console. You can also set most of these options directly in the domain.xml configuration file if you prefer.

​

• Turn Off GlassFish Development Settings
  • Turn off Auto-Deploy  & Dynamic Re-Loading. Both of these features are great for development, but can affect performance.
• JVM Settings:
  • –Xms (Initial Memory Allocated to JVM at Startup) & –Xmx (Max Memory Assigned to JVM). As we have 4GB, let’s assign half to the JVM. We should also start the JVM with all 2GB allocated so there is not work for the JVM to do in allocating memory as it goes.
  • -server (use the server VM as opposed to the Client VM). The Server VM has been specially tuned to maximize peak operating speed.

                      -Xmx2048m
                      -Xms2048m
                      -server

• Acceptor Threads:
  • Acceptor threads are used to accept new connections to the server and to schedule existing connections when a new request comes in. Set this value equal to the number of CPU cores in your server.
  • In our case we have 1 Quadcore CPU so we should set this to 4.
• Thread Pool:
  • We will set both the min and max to 100. Specifying the same values for Min and Max will allow GlassFish to use a slightly more optimized thread pool.
• Timeouts (set to 10 minutes):
  • http-listener-1 > Connection Upload Timeout: 600000 (Milliseconds)
  • http-listener-1 > Request Timeout: 600 (Seconds)
• HTTP Connections:
  • http-listener-1 > Max Connections = 200
  • The number of connections specified by Max Connections is divided equally among the threads.
• Enable Caching for http-listener-1:
  • Status: Enabled
  • Max Age: 21600 (seconds) - 6 Hours
  • Max Cache Size: 52428800 (bytes) - 50 MB
  • Max File Count: 3000
• Disable http-listener-2
  • We typically only need one listener so we disable "http-listener-2"
• ​Logging :
  • Add the ORDS logger 'oracle.dbtools'
    • oracle.dbtools.level=WARNING
  • Set all other loggers to 'SEVERE'. This will reduce the workload on the web server as INFO is the default value which generates a lot of messages.

The above settings are a guideline only for a fictitious work load. As with all things performance, you will still need to go through the exercise of adding load to your system and finding the right settings for your hardware, users, data etc. The good news is, you now know which levers to pull!

In my previous post, I opined that APEX was coming of age in the Cloud Era. Actually, I could go further than that and say APEX was born for the Cloud. APEX has been a Cloud based PaaS service before PaaS was a thing (think apex.oracle.com). It has a natural container in the Oracle Database and the development environment is purely web based. Essentially, all you need is a URL and you can get started. That's about as cloudy as you can get (yes I believe cloudy is now a thing).

Also consider how the APEX product has evolved to add a fantastic UI to it's existing data processing pedigree. There is no more powerful a data processing engine than the Oracle database. Couple that with a now aesthetically pleasing and functional UI and you have the complete web development package. Add to that, sophisticated web service hosting and consumption capabilities and the possibilities are seemingly endless.

​All of this makes APEX is a natural choice for extending Oracle's Cloud ERP. A topic which I will expand on in this post. I will discuss four use cases where APEX and Cloud ERP could meet and dive into a use case for each.

This use case was the focus of my previous post Oracle Cloud ERP and APEX PaaS Mashup. In this use case, we are focused on supplementing ERP Cloud functionality with APEX UI components embedded within the Cloud ERP UI. This approach means the user never leaves the comfort of the Cloud ERP UI.

Convert a Salesforce Prospect to a Cloud ERP Customer
​The example use case involves an APEX page being embedded in a tab within Cloud ERP. The embedded page allows a Cloud ERP user to search prospects (in real-time) from Salesforce, identify a specific prospect and click a button to convert the prospect to a Cloud ERP customer.

Behind the Scenes
When the user opens the APEX page in ERP Cloud, a Java Web Token (JWT) is generated by Cloud ERP and passed to APEX. APEX verifies the JWT, authenticates the user and returns a search page to be rendered in the Cloud ERP window. Once the user enters their search criteria, APEX calls a Salesforce REST service to fetch prospect data and displays it in a table on the embedded APEX page. When the users identifies a prospect and clicks convert, APEX calls a web service in Cloud ERP to create the customer and tag it with the ID of the Salesforce prospect. APEX will then call a REST service in Salesforce to mark the prospect as converted and update field with Cloud ERP Customer number.

The second use case involves incorporating live and cached Cloud ERP data in a  standalone APEX Application.

Consolidated Management Dashboard
​In the use case example, an APEX dashboard is built which pulls financial summaries from Cloud ERP via calls to the BI Publisher web service. This data is incorporated (in real time) with data from an on premise treasury system and financial data from a subsidiary which is running SAP. APEX provides sophisticated charting capabilities to provide visualizations for the data to facilitate decision making.

Behind the Scenes
Users would authenticate into the APEX application using their Cloud ERP credentials. The challenge here is that there is currently no user authentication service available in Cloud ERP. You can work around this by making a call to any web service using the users Cloud ERP credentials. The response will determine if the username and password are correct and allow them into your APEX application. Once in the application, you would utilize the users credentials (for the duration of the session only) to call SOAP and REST based services in Cloud ERP to fetch data.

You can build custom BI Publisher (or OTBI) reports to provide pre-summarized data in XML format and call these reports using the BI Publisher web service to pull the data into APEX. That way, Cloud ERP does a lot of the heavy lifting and you are not pulling thousands of records across the network. You will want to consider caching certain data in the local (local to APEX anyway) database. This will significantly reduce latency in making multiple calls to the Cloud ERP web services. Lookups, currency conversions and additional data manipulation can be all performed in the APEX database.

APEX utilizes a responsive theme which works great to automatically adjust the UI as you move from desktop to laptop to tablet. APEX also has excellent mobile capabilities when you need the simplicity of a purely mobile UI. This aligned with APEX's rapid application development capabilities allow you to build opportunistic mobile apps to empower your workforce.

An example use case could be to provide project managers a mobile UI using APEX that allows them to capture images of the worksite and upload them as attachments to a project in Cloud ERP.

​I won't go into behind the scenes detail here, as aside from utilizing a mobile UI, the rest of the approach is the same as my previous example.

The final use case I want to cover is utilizing APEX (and ORDS) as a light weight integration platform. When used in conjunction with APEX and ORDS, the Oracle database has pretty much everything you need to integrate your cloud SaaS solutions. The database provides a scheduler for scheduled events, there are AQ tables for queue based integration patterns, PL/SQL for orchestration, mapping and transformation logic, local tables for data storage, APEX APIs for consuming REST and SOAP services and finally ORDS to host REST endpoints.

At this point, I can almost hear the sharp intakes of breath from the SOA purists. I would say, however, if you are advising your small to mid-size Cloud customer, can you honestly justify thousands of dollars a month for the all in solution when you could be spending as little as $175/month for Exadata Express? I am not advocating GE do it this way but it is fit for purpose for many customers.
​
Use Case: Employee Synchronization
An example use case is a customer who needs to sync employees between Workday and Cloud ERP. A scheduled database job in your APEX database runs and pulls employees added/changed in the past 5 minutes in WorkDay. I then performs transformations on the data and calls a REST service in ERP Cloud to propagate the change there.

​Guess what, because we have APEX in our database, we can build automated email alerts when something goes wrong. We can also build a monitoring UI to keep track of what's going on.

While not directly related to this blog, I do want to mention that at the time of writing this post, Oracle seem to be in the process of moving their Cloud ERP SOAP web services to REST. Currently, the Human Resources and Projects modules have good REST coverage. I am fervently hoping that Cloud ERP's trend toward REST continues as it will open the door for a lot of innovation (and greater adoption) of these valuable integration points.

I would be remiss if I did not mention that you need to be extra careful with security. In all of these use cases, we have web applications exposed to the internet. APEX has excellent security capabilities and is actively monitored and patched by Oracle to keep up with today's security demands. You do, however, need to make sure you follow best practices when developing your APEX applications.

Please do talk to your Oracle Salesrep regarding an potential licensing implications regarding the above. 

To be honest, we are barely scratching the surface in terms of possibilities. I do hope you can see some of the potential for utilizing APEX as a PaaS platform for Cloud ERP.