I was asked a question today which I realised after a bit of pondering, I’d been asked several times before at different companies. Us technical folk assume other’s know about what we know in relation to IT, and yet most Project Managers don’t make the effort to actually check and explain. What am I talking about? In this case, APIs.

I’m not going to re-invent the wheel here, you can read in-depth about what an API is here but certainly working on Digital web projects, system integration comes up again & again. It’s really important you know about how to tackle a web integration project, and the nuances around APIs and what hurdles and pitfall’s to look out for from a client, PM and developer perspective. So, what is an API?

In summary, an API or (Application Programming Interface) is a toolkit and in effect, ‘way-in’ to a web service and details and documents what you need to do to access that web service, whether your a human being, or (more commonly) another piece of software. You know how you use your Facebook credentials to log into Spotify? Or authenticate against your Hootsuite account by using your Twitter details? Well, that’s all thanks to an API. APIs need to be documented well to be useful. If well written documents exist, (usually as part of a SDK or software development toolkit) you can be sure your web developer will go off, a happy bunny, with all the building blocks he or she needs, to develop a web service which can communicate with the given platform.

Problems arise however, when the API document doesn’t exist. Worst still, a Project Manager who accepts a project and creates a woolly document expecting the agency-side developer to fill in ‘the blanks’ with regards to how the web service should work.

Firstly, let’s look at a typical API graphic, showing two systems which need to pass information to each other;

Whilst rudimentary, if we assume System 1 is an existing customer booking system say, and system 2 is our intended web service, we can see the ‘call’s or requests each system makes to present information. Cust. ID from the existing system is listed as Customer Name in our web service etc. At the bottom, you can see an example of where user input is taken from the new web service, maybe customer lookup for example, and the web service needs to go off, inspect the existing system and give back the full address.

This type of graphic is pretty common in API guides at a high level, and the idea being is as-a-glance, we can see what each respective system names its various database fields (remember, ultimately all online data is just going to be some form of database)

Some questions you really should be asking and considering are;

1) Is the existing system (in this case, system 1) documented? Is there an API guide available?

2) Does the client expect you (the web company) to audit the existing system and ‘work it out’?

3) What formats does the existing platform accept, in terms of data import and export?

4) What is the size of the data being passed two and from each system?

5) What does the data being passed from one system to another look like? Integers? Strings? Alphanumeric? What length?

6) Is there a developer of the existing system available to answer technical questions?

7) What language does the platform speak? .NET, .php or something more bespoke?

The questions above time & time again don’t get asked at the start of a project and can really impede on the success of a web integration project. I’ve only really skimmed the surface on web service integration, but if your a PM, take some time out to learn the scope of what an integration project looks like. Other client-friendly questions can include;

1) What information are we trying to access?

2) What is the purpose of displaying this information?

3) Is there a better way?

4) What happens if the existing web service is updated or get’s broken? What failsafe’s are present?

Security – If your names not down, your not coming in

I’ve worked on integration projects for process heavy companies such as banks, and understanding the IT security requirements needed will help your integration project along to ultimately, success. Think about the types of questions you are going to be asking as a third party web company;

1) Who deals with security at the client site? Web services and software sit on servers, behind firewalls and are subject to rigorous control access. Who’s providing usernames and passwords for the web service?

2) Do firewall’s need opening at both the client site and the web company site? If so, what ports need opening? Will these be different in test (staging) and live environments?

3) Do any change control measures need to be taken into account? One client I worked with required three weeks notice to implement any change to a firewall, you can imagine how this impacted the project delivery time scale. Find out first, what the process is by your client.

Even starting to consider some of the above, will make you more informed, and give your developers an easier time.

Got some thoughts? Tweet me at @mariodc