This article was originally written for Iguana 5 and contains version 5 screenshots, and may contain out of date references.
If you are a vendor that is planning on doing dozens of interfaces with Iguana with a team of people it’s worth spending a little bit of time thinking it through.
First of all it’s a good idea to have a standard module to wrap up your interface. This standard module should be the gold standard and not something that gets edited on a day to day basis by your team. You should use it as the foundation for all your interfaces that you implement.
Here some key ideas to consider when implementing this standard module that I think make sense.
Think in terms of an API to your application. Sometimes you might not be there yet. Let’s say the way interfaces are done in your company is that you feed directly into database tables. Well you can still think ahead and build out your standard module on top of that. If you do it that way then it opens things up to have replace that direct database model with say a RESTful web api then if you have been smart with using a standard module means you won’t have to rewrite all your interfaces when your application does have this capacity.
A good API is like a good filing system. Ah the glamour! But it’s true. A good interfacing API or module should really just have a well thought out naming scheme with really obvious places to put things. You should get someone who spel good to design your API (joke). A bad API is where everyone files everything under the “Miscellaneous” section. Good luck with retrieving data out of that. It’s a more common problem than you think. I have seen many a company screw itself over where all the interfacing people formatted structured data and put it into a “note” field.
Don’t couple your API to a specific protocol. One common goofball mistake that people make is to tightly couple their interface to a protocol they are intimately familiar with. For instance if you are used to HL7 you might be tempted to make an ‘API’ which is rigidly follows the structure of HL7. This can happen in the most innocent ways – it’s common approach for instance for people to build their interface on what they think of as their ‘canonical’ HL7 implementation – but this approach makes one’s interfaces very inflexible.
Support Batching. For this one think back to basics. Think of a classical hard drive. Seek time to move a disk head to part of the disk is slow. Writing 1k or 1000k is about the same time. This pattern repeats itself at many levels. If you insert 100 rows of data in a database in a single transaction it’s faster than running 100 transactions inserting one row at a time. So if you can build your API to support batching then it’s a good thing for enabling handling higher volumes of transactions.
Leverage Iguana Help. It’s easy to use Iguana’s built in help system to document the functions in your standard module. It makes your API a lot more user friendly for the implementation team. There are other tricks I find can be handy too. For instance say you have a interface to your application which can be easily expressed a tables of data – i.e. rows with names in them. Then using the database schema definition format can be really nice because it has really nice annotations.
For example I recently threw together an example API for a OEM we are working with which I’ll call Patient Power. This screen shot shows some of the techniques I describe above:
See how we get the set of interfaces to populate with the init method and then pp.exec() is called to consume the mapped data. How that pp.exec() is implemented can be changed, without invalidating the work put into the mapping.
Got questions? Do feel free to reach out and ask.