This post is my contribution to the Oracle Developer Community (ODC) Appreciation Day. The idea of the event is best explained by Oracle Base – go here.

The Apiary Editor has to count as a pretty new entry into the possible features that could be considered with Apiary only coming into the Oracle family in the last year. Apiary as a solution provides a platform by which modern REST based APIs can be designed, documented and simulated. Apiary supports the API First design philosophy (more here) using API Blueprint notation or Swagger (now known as Open API).

The feature I want to focus on is the Apiary Editor itself (shown below), particularly when working with the API Blueprint.  The beauty of the solution is that as the documentation or API syntax is edited in the editing side (left)  the API definition/documentation immediately appears on the presentation side of the editor  (right) making it easy both see the technical specificastion and how the information is initially presented to a potential API user. This makes it really easy to understand the clarity of what is being communicated which is one of the important aspects of an API definition and API first.

Whilst Agile development states ‘prefer working code over documentation’ this provides agility as you can develop the API definition and allow people to develop against the contract we can still easily deliver quality API descriptions with sufficient information to make it understandable to a 3rd party.