Hero #18
Posted on 12 January, 2017 by Balbir Bhogal & Riaan Ingram

Using an OpenAPI specification in Oracle Service Bus 12c

With the momentum shifting to APIs and specifically RESTful APIs there are a lot of questions around how to start down the road to APIs when talking about integration or ‘API-led connectivity’. Many companies have an existing integration capability, middleware or an ESB and want to reuse that significant investment to govern an API-led connectivity approach.

A very important factor in governing API-led connectivity or an integration approach is the Contract First design approach. In this blog we will detail one approach to utilize the most common RESTful API contract standard, the OpenAPI Specification (formerly Swagger) in Oracle Service Bus 12c (OSB).

The key steps are:

  • Obtain sample json structures
  • Generate nXSD structure
  • Generate XQuery

Obtain sample json structures

In order to generate the json in JDeveloper (the “json interchange format”) you first need sample json structures that adhere to the OpenAPI contract. In the below example we have used the swagger editor to obtain sample structures, but you could use any other tool like an API Gateway Portal for API Consumers that contains API contracts.

Open the online Swagger editor “http://editor.swagger.io/#/” . Next click on File > Import File > choose file > Import (browse and choose your Swagger API yaml or json file). On the editor screen scroll down and on right side click on “Try this Operation” button

Insert values in the parameters, this will create a url with query string as shown below. Populate repeating structures for arrays so they show up in the output.

Capture the resultant json and copy that to a text file.

Do this for the all input payloads and output payloads. Copy & paste the output $ref to the input operation sections (as shown above) in order to do the same for the output json objects.

Generate nXSD structure

In order to utilize the Swagger constructs in JDeveloper in a similar fashion to using XSDs, you need to ‘import’ the sample json structures into JDeveloper as some form of XSD equivalent, nXSD which is the json interchange format. Open JDeveloper and in an OSB Application then right click on project

New > From Gallery > search for “nxsd” > select “ NXSD Schema (XML)” > ok

Click on Next > Give a File name > Next > select “JSON Interchange Format” > Next > Browse for the text file containing the json samples generated in the first step > Next > Test > click on green arrow button > if successful then click on ok > Next > Finish. Do the same for all the request and response payloads.

This nXSD XSD schema can also be used in a WADL.

Implement translation

This steps shows how you use the artefacts previously generated in a typical development scenario i.e. effectively use the OpenAPI contract in an OSB development. In an OSB proxy pipeline flow, insert an ‘nXSD Translate activity’ and pass the variable with the json payload into this activity.

The above nXSD Translate is used to convert from XML to Json and can also do the json to XML (e.g. for the response payload).

In summary, this provides a workaround for importing OpenAPI specifications into Jdeveloper and using the structures within the specification in an OSB pipeline flow, thus closing the gap between design and development ultimately increasing accuracy & quality of developments.

Back to blog
Balbir Bhogal
SOA Developer

Balbir is a SOA Developer with 10 years’ experience in IT design and development. He specialises in integration technologies and has in depth knowledge of the Oracle Fusion Middleware platform.

Riaan Ingram
Principal Consultant (Architecture & Integration)

Riaan is a Principal Consultant with over 18 years’ IT design and development experience. Riaan has a strong technical background and specialises in developing and integrating enterprise business solutions. Riaan has in depth knowledge of integration as well as cloud patterns & technologies and is an expert in the planning, design and implementation of API first integration approaches.