Converting ADLs to implement end to end JSON in SOA Suite 12.2.1 -PART I
There is no doubt that web [Rest] APIs have become extremely popular and its usage has gone well beyond just building APIs in support of mobile apps. We can see the adoption of resource-oriented architectures (ROA) by probably all SaaS vendors who provide out-of-the-box APIs as the means to connect and interact with their cloud applications. Take for example the Oracle Cloud. To discover and consume publicly available Oracle SaaS APIs, all one need to do is browse the Oracle API Catalog Cloud Service (which is publicly accessible) and just select the Swagger definition for any given API.
But (as you probably already know) the adoption of web APIs hasn't stopped there. With the increased popularity of Microservice Architectures , initiatives such as Open Legacy , and node.js based frameworks like loopback and sails (to name a few), API-enabling system of records is becoming a lot easier.
This is putting a lot of pressure in software vendors to quickly modernise their integration suites to natively support the technology-stacks and patterns prevalent in these type of architectures. For example, if an organisations mobile application needs to interact with a system of record (on premise or the cloud) that already exposes a web API, the integration stack should be capable of supporting JSON over HTTP end-to-end without having to convert to XML back and forth. Not only is this impractical but introduces more processing burden to the core stack...
Luckily for many Oracle's customers and Oracle Fusion Middleware / Oracle PaaS practitioners like myself, with the latest release of Oracle SOA Suite (12.2.1) , one of the many new features introduced is the support for handing JSON end-to-end. I don't want to understate the importance of this as with such feature it is possible to use BPEL for example to orchestrate several APIs (all in native JSON and also in-memory with the new SOA in-memory feature) and therefore deliver coarse grained business APIs that actually perform.
For me this represents an important milestone for Oracle SOA Suite as it shows the departure from traditional SOA tech-stack and into SOA 2.0 (as I like to call it) as the suite is now better suited to support the adoption of ROA, microservices, IoT, and so on. Having worked with SOA Suite since 10.1.3.1 this is very exiting.
The catch
Unlike traditional SOAP services that make use of web service description language (WSDL) as the main mechanism to define a service interface (yes one can argue that there are different types like doc-literal, rpc-encoded and versions like 1.1, 2.0, broadly speaking they are similar and there is vast support for all of them), web APIs don't enjoy this mono-linguistic nature, in fact quite the opposite.
There is at least 8 different API description languages (ADL's) that am aware of. Some more popular than others but still in general all with substantial communities and vendor support:
Note: Suggest you go through this presentation for a good overview of the main ADL's
Oracle on the other hand didn't opt for endorsing or fully adopting any particular ADL. Instead it seems that conway's law came into action and different products currently support different ADLs.
Although I am sure that this inconsistency will go away in future releases, for us practitioners this sort of represents an immediate challenge. Even though all of the aforementioned do support REST/JSON in its purest sense, not being able to interpret an ADL automatically using an adapter basically means that one has to manually configure the URIs, resources, methods and parameters in a REST adapter in order to successfully consume the API.
Let's take for example the following Swagger ADL for the Oracle Field Service Cloud activities API (for which there isn't yet an out-of-the-box adapter in SOA Suite or ICS) :
https://apicatalog.oraclecloud.com/v1/services/oracle-public/ofsc-core/v1/apis/activities/canonical
If you clicked in the above you'll notice that tons of resources and methods are available (82 methods and 13 resources approximately). So imagine having to manually enter all of these in JDeveloper to configure the SOA Suite 12.2.1 REST adapter.. Yes possible but by any means practical. Far from it.
The solution
There is however a work around to this and its called API-Transformer
Developed by APIMATIC , API transformer is an online tool for converting ADL's and it supports the most popular formats (including all of the aforementioned ADLs):
Best of all is the fact that API transformer is also an API on its own right. Meaning that one could use this public API to build some sort of automation to facilitate the conversion between the Oracle supported formats.
Conclusions
APIs are great but the technologies and standards around it are still evolving. However the industry doesn't seem intimidated by this as the adoption of APIs continue to increase exponentially. Meaning that we practitioners are left having to deal with the complexity of adopting evolving paradigms without jeopardising the benefits that can be gained from their adoption. Luckily there are tons of open solutions out there that can be used to work around some of these complexities and API transformer is a good example of such.
In part II of this article I will show step by step how to consume an API defined in Swagger 2.0 from SOA Suite 12.2.1. For this I will transform the Swagger ADL to WADL, import it into a composite application using JDeveloper and the REST adapter and then implement end to end JSON to expose a generic API.
But (as you probably already know) the adoption of web APIs hasn't stopped there. With the increased popularity of Microservice Architectures , initiatives such as Open Legacy , and node.js based frameworks like loopback and sails (to name a few), API-enabling system of records is becoming a lot easier.
This is putting a lot of pressure in software vendors to quickly modernise their integration suites to natively support the technology-stacks and patterns prevalent in these type of architectures. For example, if an organisations mobile application needs to interact with a system of record (on premise or the cloud) that already exposes a web API, the integration stack should be capable of supporting JSON over HTTP end-to-end without having to convert to XML back and forth. Not only is this impractical but introduces more processing burden to the core stack...
Luckily for many Oracle's customers and Oracle Fusion Middleware / Oracle PaaS practitioners like myself, with the latest release of Oracle SOA Suite (12.2.1) , one of the many new features introduced is the support for handing JSON end-to-end. I don't want to understate the importance of this as with such feature it is possible to use BPEL for example to orchestrate several APIs (all in native JSON and also in-memory with the new SOA in-memory feature) and therefore deliver coarse grained business APIs that actually perform.
For me this represents an important milestone for Oracle SOA Suite as it shows the departure from traditional SOA tech-stack and into SOA 2.0 (as I like to call it) as the suite is now better suited to support the adoption of ROA, microservices, IoT, and so on. Having worked with SOA Suite since 10.1.3.1 this is very exiting.
The catch
Unlike traditional SOAP services that make use of web service description language (WSDL) as the main mechanism to define a service interface (yes one can argue that there are different types like doc-literal, rpc-encoded and versions like 1.1, 2.0, broadly speaking they are similar and there is vast support for all of them), web APIs don't enjoy this mono-linguistic nature, in fact quite the opposite.
There is at least 8 different API description languages (ADL's) that am aware of. Some more popular than others but still in general all with substantial communities and vendor support:
Note: Suggest you go through this presentation for a good overview of the main ADL's
Oracle on the other hand didn't opt for endorsing or fully adopting any particular ADL. Instead it seems that conway's law came into action and different products currently support different ADLs.
Although I am sure that this inconsistency will go away in future releases, for us practitioners this sort of represents an immediate challenge. Even though all of the aforementioned do support REST/JSON in its purest sense, not being able to interpret an ADL automatically using an adapter basically means that one has to manually configure the URIs, resources, methods and parameters in a REST adapter in order to successfully consume the API.
Let's take for example the following Swagger ADL for the Oracle Field Service Cloud activities API (for which there isn't yet an out-of-the-box adapter in SOA Suite or ICS) :
https://apicatalog.oraclecloud.com/v1/services/oracle-public/ofsc-core/v1/apis/activities/canonical
If you clicked in the above you'll notice that tons of resources and methods are available (82 methods and 13 resources approximately). So imagine having to manually enter all of these in JDeveloper to configure the SOA Suite 12.2.1 REST adapter.. Yes possible but by any means practical. Far from it.
The solution
There is however a work around to this and its called API-Transformer
Developed by APIMATIC , API transformer is an online tool for converting ADL's and it supports the most popular formats (including all of the aforementioned ADLs):
Best of all is the fact that API transformer is also an API on its own right. Meaning that one could use this public API to build some sort of automation to facilitate the conversion between the Oracle supported formats.
Conclusions
APIs are great but the technologies and standards around it are still evolving. However the industry doesn't seem intimidated by this as the adoption of APIs continue to increase exponentially. Meaning that we practitioners are left having to deal with the complexity of adopting evolving paradigms without jeopardising the benefits that can be gained from their adoption. Luckily there are tons of open solutions out there that can be used to work around some of these complexities and API transformer is a good example of such.
In part II of this article I will show step by step how to consume an API defined in Swagger 2.0 from SOA Suite 12.2.1. For this I will transform the Swagger ADL to WADL, import it into a composite application using JDeveloper and the REST adapter and then implement end to end JSON to expose a generic API.
Comments
Post a Comment