Describing ORDS RESTful Services using a WADL

-
Recently I got this question (or better specification) from a customer: 
"For exchanging data, we either want a SOAP webservice or a REST service offering a WADL". 

WADL? 


 What's a WADL? I know WSDLs as descriptive endpoints for SOAP webservices, but WADL?! It occurs, that WADL's are intended to do just that, but in a more generic way. WADL stand for Web Application Description Language. The World Wide Web Consortium (W3C) currently has no plans to implement WADL as a standard. Oracle's ORDS is going the swagger/openapi route which is partially implemented in the 17.3 release. 
With no existing functionality to provide a WADL for Oracle RESTful services, I had to come up with my own solution, using the APEX repository views to generate a WADL endpoint. I came up with a small procedure for this and add an additional URI Template to my service, called "wadl" with a single GET Resource Handler calling this procedure. 

WADL endpoint in APEX RESTful definition
Because the RESTful service I had to provide was fairly simple, my solution is far from complete. In addition, the WADL definition structure examples I found were not really clear on which elements to include or not. So, I decided to provide my solution as a GitHub project, open for anybody who wants to contribute. In addition, I have used my procedure to provide a WADL on the "oracle.example.hr" example RESTful service in my Oracle Application Express workspace on apex.oracle.com. After some modifications (on the example), I was able to load the definition into SoapUI.
Import a WADL in SoapUI

 Give it a go. You can reach it here: https://apex.oracle.com/pls/apex/fifapex/hr/wadl/ 

RESTful Module oracle.example.hr in SoapUI from imported with generated WADL

Naughty APEX RESTful service definitions 


 I tested the generated WADL with SoapUI, and the program does show all the handlers defined including all parameters. Unfortunately, a WADL is somewhat stricter then an APEX RESTful service definition when it comes to case-sensitivity. Parameters have to case-match the resource path definition, which wasn't the case in the oracle.example.hr RESTful example. The 5.1 example has one definition per resource/URI template. In earlier version, I have seen multiple definitions with the same URI resource path (for example employees/{id}), and in the APEX RESTful repository, parameters are always stored as child records of a resource handler (PUT, GET, …), while parameters can either be on resource template level or on handler level. Makes sense, as the {param} part of the path belongs to the resource, but you might want to pass some HTTP header parameters with the PUT request for a resource only, while the GET just needs the resource parameter. Not all parameters from the resource paths were defined as parameters in the resource handlers, so I had to add those. I provided an export of the "corrected" example RESTful service on the GitHub project of my WADL generator procedure. 

Contribute 


 Well, I have a reasonably well working WADL generator for Oracle ORDS/APEX RESTful services now. It sure needs improvement for other cases, I bet. So, if you need to provide a WADL for your RESTful service in APEX, get the code from my GitHub project. If you have enhancements, please contribute to the code. 

Comments

Post a Comment

Popular posts from this blog

Remember Me - APEX Autologin

-
Image
I promised to publish about this subject to one of the attendees during my presentation at KScope 12 in San Antonio. I used this functionality in my demo application ( FifApex ) and it seems there is interest in how to do this. Most of the public websites like Facebook, LinkedIn, Twitter, Amazon or OTN do have it: an option to stay logged in, even if you closed the browser, so you do not have to authenticate each time you visit the site again. I’m pretty used to it and would be surprised if a website didn’t offer this convenient feature. OK, it’s not entirely secure, but, as I said, very convenient. I’m working on a “consumer” site/application, I’m building it with APEX and I want to offer this “remember me” option too. I knew an APEX based website that does offer this feature ( www.plsqlchallenge.com ) and I had a chat with the developer that implemented it’s login mechanism, Paul Broughton from Apex Evangelists . So, here my thanks to him for the original inspiration.   Or...
Read more

Dynamic Date Range in APEX Datepicker - no Plugin required

-
Image
The build in jQuery UI Datepicker of Application Express is a very versatile component and it is very easy to configure the basic settings with the Page Item properties. One of the properties you can set, is the range of selectable dates by entering a Minimum and Maximum Date value. The “syntax” of these values is based on the jQuery UI Datepicker components date format capabilities, so this might be looking a bit awkward to us Oracle folks at first sight. Next to giving a static value or one of these Datepicker calculations you can reference an APEX Page Item to set the range values, which is a nice thing as we are able to calculate a range dynamically, based on some database value/calculations. The bummer is: the calculation only gets executed during the rendering phase of the page and changing the referencing Page Item’s value won’t change the Datepicker range. What you really want (yes, you do), is to be able to reference Page Items to control the Minimum and Maximum Date dynamica...
Read more

Tabular Forms on Complex Views - using INSTEAD OF Triggers

-
Image
Creating tabular forms in Apex is relative straight forward. One gets fully generated, instant insert/update/delete functionality. Unfortunately (for the form developer), tables are usually part of a more or less complex data model, which is optimized for data storage, rather then for form-layout. Well, Apex offers some possibilities to the developer to enable tabular forms beyond 1:1 table based. Collections One alternative is to create your tabular form using the Apex Collection API. There is a good article on Martin Giffy D'Souza’s blog describing this technique. This collection-approach basically pre-fetches data into a (PL/SQL) collection from a query/cursor. The “collected” data will be displayed in the form. An on-submit page process will store the data submitted from the form into the collection. After this you can perform some validation before submitting the data to table(s) in an on-submit page process. Database Views Well, I favor an approach that keeps the...
Read more