Friday, December 22, 2017

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 LanguageThe 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 parametersUnfortunatelya 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. 

No comments:

Post a Comment