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