Actual articled date: Sep 25, 2016

As I have touched on briefly in a previous post, Procuring Event Technologies? Know the technical jargons, API stands for:

“Application Program Interface”. In layman’s terms, an API is an agreement between two systems stating: “If you give me this instruction, I will perform this action, or return this information”. It is a list of commands a program can send to each other; simple as that.

Recently there’s keen interest from organisers with regards to API integrations as the promise lies in connecting different vendors or systems and letting them all talk to each other seamlessly.

However our experience with API integrations are not as rosy as it seems. It often than not can end up with a lengthened integration process which throw up added costs from vendors due to technical inadequacy from vendors to integrate. This is especially with legacy vendors who are struggling to wake up to the notion of APIs playing an important role in the event technology sphere where everything will be more inter connected.

This article hopes to equip organisers with in-depth knowledge about APIs and truly understand how to fundamentally judge what really constitutes API integrations and gauge the best approach to kick start integration.

Lets first bring in the context of why no two APIs are created the same.

First.. Integration with an API is a mono-directional process

I have found that API is a loosely used term in the field of event technologies where the definition of API is very much in the grey area. Most people when using the term, doesn’t really understand the process.

To make clear of any API integration process we should all first understand the stakeholders involved in this process.

1. Client
A client is typically the organiser, who commission an API integration project with specific details of the expected outcome.
2. API Provider
An API Provider provides the relevant API documentation that will be required for the expected integration outcome.
3. API Receiver
An API Receiver uses the API documentation and does the necessary programming to fulfill the client’s integration outcome.

All API integration process involve two main parties, the API provider and the API receiver. The API provider provides the API documentations and structure of how data can be transferred to the API receiver. The API receiver simply uses what is provider to integrate. All APIs documentations are key for the API receiver to allow seamless integration.
Imagine going into a restaurant (API provider) and opening up a menu (API documentation) to pick what you (API receiver) would like to eat today.

API integration function on a similar idea.

Second.. An API should be judged by it’s quality

You must have experienced inadequate menus before. Some inadequate restaurant menus does not describe how each item is prepared or consist of what ingredients. Some menus are written with illegible writings or simply printed lousily. Some menus can be in another language which you will not make any good sense of. Some restaurants dont even have a menu to speak of.

In a nutshell, API documentation quality can vary and sometimes, do not even exist at all.

Here are the typical scenario that you as a Client will most often fall into:

Scenario #1 — There is no “menu”!
The API provider asks the Client the kind of integration they are looking for and will most often than not says that they have an API in place already. However when probed to provide an API documentation, they have none to show. They carry on to assure the client that they do have an API, depending on the use cases.
Once the specification of what the Client is trying to integrate with the API receiver is made known, API provider charges a fee to “provide” the API. Behind the scene, they scramble to write out the API process.
This is the most tricky scenario as the project can enter into a gridlock, require extended amount of time (instead of starting on integration, the provider has to create the API first) or simply, falls into Scenario #2 next.

Scenario #2 — “Menu” is inadequately documented
When a “menu” is inadequately documented, it often leads to more cost from the API receiver ends as it will be required to do extra testing, understanding and sometimes even help the provider to improve their “menu”.

Scenario #3 — Well crafted “Menu”. Bon appetit!
This is typically when the the integration starts off on a good and direct note. The provider understands the documentation and starts on the integration work.
Most of the time, the provider will not be charging to use the API (although there are providers who will take the chance to charge a “cost” anyway. The “cost” should be much less than Scenario #1).
There will be a charge on the receiver side as custom integration work has to be done to feed the data into the right place.

Third.. An API goes beyond it’s documentation

Having a “menu” is good but the ingredients and cooking style that goes into preparing the dishes must be capable to deliver quality too.

This is when reliability of the API comes into play. The API provider’s server that hosts the API can go offline, due to multiple reasons. It may also be rendered unusable due to system or coding errors. Typically, the API receiver will follow an API documentation closely and will program to the expected and consistent behavior of the API. However, sometimes the API can throw up an unexpected response, breaking the API receiver’s code.

In short, a functioning API need to be reliable, stable and consistent.

But what happens when it is not so?

It typically will cause the API receiver code to go offline or enter into error mode too as the response from the API is either non-existent, or unexpected. This will definitely incur cost on the client side if the API receiver is expected to do more work to bring the code online or fix an inconsistent response by expanding the expected response cases.

As the owner of any integration work, I truly believe that organisers can appreciate and guide integrations on the right path by understanding what the API integration process entails.

More often than not, a successful integration outcome will create tremendous value to your customers — by using integrating the best tools in the market -, as well as to your internal processes — through automation -.

‍