Introduction

The API Designer is a new cloud based software tool from iNTERFACEWARE.  It’s first application is to make it easy for Iguana users to build, share and test intuitive web APIs for integration.  We have a very active roadmap ahead for this application to make it useful for solving other problems.

You can log into the API designer from:

https://designer.interfaceware.com/

Web APIs are the future of integration in healthcare, but creating a high quality API can be a challenge.

A good quality API needs the following:

  • Good documentation.  Many companies have trouble keeping documentation for their APIs up to date with the actual functionality.
  • Consistency.  Because most web APIs are programmed by hand by different developers over time many APIs get to be inconsistent in the language and conventions they use.
  • Error Handling.  A good quality API checks its inputs, and returns helpful error messages when a software client makes a mistake in how it is calling the API.
  • Easy to use.  It should be simple to call the API without requiring specialized tools to invoke the API. RESTful interfaces have become more popular than older SOAP based interfaces because they do not require special libraries to invoke them.
  • Modern JSON based.  Today’s modern developers expect APIs to use JSON – this is the easiest most widely adopted standard data format.

The API designer enables all these goals.

It provides an intuitive web based editor which makes it easy to write the definition for the API together with the documentation.  Having this documentation for the API makes it simple to ensure that consistent language is used through the API.

The API designer is built using a simple JSON based schema language which describes the APIs used.  This makes it easy to implement intuitive error handling and makes it easy to use APIs built with the API designer.

Having a grammar to describe the API enables us to build a Lua client adapter for APIs built with the API designer which automatically discovers all the methods exposed in the API and makes it easy to form JSON objects used by the API.   However it is not necessary to use Iguana nor have any special library to call these APIs.  These APIs can be called just like any other modern RESTful web API without any special tools.

The generated APIs are close to RESTful in philosophy but simpler in that data can be taken in either as

  • Name/value pairs with GET/POST variables, or
  • As JSON formatted in the body of the requests
  • The APIs are agnostic about whether one uses HTTP GET or POST – they will work with either.

The returned data is always formatted in JSON.

This makes building and using the APIs simpler since one doesn’t have to pay as much attention to how to call the APIs with HTTP concepts. Instead focus can be placed on the value of the data being exchanged.

Leave A Comment?