Apiary and APEX

More and more projects I work on at the minute make use of RESTful Web Services. These can either be a way of exposing our own data or a way to make use of data from external systems.  They are easy to create in the Oracle Database to surface your own data – check out Colin’s blog if you want to see how https://explorer.co.uk/web-services-part-1/. From APEX 18.1, the web services you create through the APEX front end are created in exactly the same way as when using ORDS and any ORDS created web services are visible in the APEX front end.

So it’s nice and easy to create web services, and we’ve covered that lots of times, but what about using external web services in your APEX application? & If you have experienced this before then you might remember some web services you considered to be “good” and some that you considered to be “bad”. In my experience, a good web service is the following:

• Adheres to standards.
• Well documented.

It makes your job as a developer much easier if the web services you have to incorporate are sensibly created, easy to navigate and are documented well so that you can easily plug them into your code. But do you always provide this with the web services you create for other people to use?  This is where a tool like Apiary can really help.

What is Apiary?

Apiary is an Oracle owned piece of software which allows you to design, create, document and share APIs. The idea is that you design your web services fully in the specification stage and work closely with the end users of the web service to make sure that it provides everything they need.  Apiary can help you create mock web services that can be called by your end users to test that they meet any requirements.

Web services are written in either API Blueprint or Swagger and as you write them, interactive documentation is generated by Apiary. This documentation is the end result that you will surface to end users/developers to allow them to navigate the web service and see what options are available. It is also possible to generate code-snippets to allow you to call the web services (either live or mock) and even test each call directly from within the Apiary front end.

How does this relate to APEX?

The API-first approach is all well and good for large projects incorporating multiple technologies, but with the low-code nature of APEX, you can quickly create an application with web services on top to serve an urgent business purpose. And what about all those APIs you have created in the past?

There is a handy button in the new APEX ORDS based RESTful services interface named “Generate Swagger Doc”.

For each web service module, you can click this button and generate some Swagger formatted code defining your web services. This should look something like the snippet below (this screenshot is from apex.oracle.com, which opens directly into the swagger editor. Hopefully this is a feature in future APEX versions):

Once you have this code, all you need to do is paste it into Apiary and you will end up with navigable documentation for your existing web services.  You can even create code snippets or test the web service from the Apiary front end. A great addition to your documentation that you can get without doing any work.

If you’d like to have a go, you can have a look at my example documentation here: https://webservicedocumentationforblog.docs.apiary.io

Going forward, as web services become a bigger part of APEX development, it will be useful to be armed with a tool like Apiary or SwaggerHub (non-oracle) to make sure that your web services are well designed, well documented and can be easily used by any other team that wants to build a front end on top of your functionality.

While there is a free version of Apiary, you will need the Oracle Cloud version to create private documentation. This isn’t currently a cheap option, but it is included with various cloud offerings and is perfect for documenting your APIs across your whole Oracle stack.

Author: Craig Sykes 

Job Title: Senior Oracle Development Consultant

Bio: Craig is a Senior Development Consultant at DSP-Explorer. Craig has an MSc in Computing Science and is an experienced software engineer, utilising development tools such as PL/SQL and APEX to provide bespoke ERP software to both UK and international businesses. Craig has experience developing solutions to connect Oracle systems to a wide range of existing external applications within business environments.