Main Image

Dummy's guide to APIs

Paul - 26.11.2015

APIs are used across an organisation, from CRM systems to marketing, accounts to order processing and delivery. They’re the domain of techies so you could argue that you don’t need to worry about how they actually work. But because they’re so essential in connecting your organisation and the quality of APIs has such an impact on your development team, shouldn’t you at least know the basics?

This guide will answer some fundamental questions about APIs, using as little technical language as we can manage.


What does API stand for?

API stands for ‘application programming interface’

What does an API do?

An API is a set of instructions and standards that govern how one application can talk to another. By making some of their internal functions open and accessible, APIs make it possible for applications to share data without software developers having to expose all of their code.
The best analogy we’ve come across is comparing APIs to the back of your television set. Your TV allows other appliances (DVD players, cable TV, games consoles etc) to interact with it to deliver more functionality than the TV does on its own.

Why would you use an API?

An API allows data to be transferred between different systems within a business, meaning processes are joined up and businesses can use their data better.

They enable a particular audience to use data more quickly, easily and efficiently when they are looking to do something specific with the information.

As consumers we benefit from APIs every day – particularly through our interactions with social media.

From a business perspective, APIs enable an organisation to improve operational efficiencies – for example, by allowing a warehouse management system to pass data onto a delivery management platform. This will streamline the order process for retailers.

APIs that you’ll already know

As a consumer you’ve probably logged into a new app using your Facebook account but there are straightforward business APIs that you’ll recognise too. Salesforce, for example enables staff across the organisation to manage customer relationships better, by linking up sales, marketing and customer service software.

Google Maps – the Google Maps API enables you to embed Google Maps on webpages

YouTube – this enables you to integrate YouTube into websites or applications

Twitter – Twitter offers an API that gives you access to core data on Twitter. It also has a search API that enables you to interact with Twitter search and trends data

How does an API work?

There are different types of APIs – for operating systems, applications or websites. Web service APIs for example use the internet to exchange information in the form of an HTTP request. This HTTP, or ‘Hypertext Transfer Protocol’, request essentially means that one application can speak to another application in a format that the other application can understand, and vice versa.

What are the main types of web APIs?

REST (Representational state transfer)

A simple and flexible API – no extensive tools are needed to interact with it. REST is fast and developers are not tied down to one language or data structure when using it.

SOAP (Simple Object Access Protocol)

Originally developed by Microsoft, data is transferred in xml format. SOAP has a more rigid set of messaging platforms than REST, but has in-built error handling so if there’s a problem with a request, information is given to allow the problem to be fixed.

What’s the difference between an open and closed API?

An open API is one that is publicly accessible – i.e. anyone can access and use it. A good example is Twitter – anyone can register for and use Twitter’s API.

A closed API is essentially private and has controlled and protected access. The Electio API is a good example. In order to use it you need to have an authorised account.

Does API integration put a massive strain on internal resources?

Depending on the API this can vary hugely. A good API is well-documented and easy to use. If the API follows common standards and practices then there is usually very little drain on the team trying to work with it.

In some cases you can even get a Software Development Kit (SDK) written by the API developers. This allows customers to interact with the API with very little coding required at all – simply supply a few configuration settings and they can interact with it immediately. This also makes it easier and faster for software developers to write programs that work with the API. A good one should contain plenty of reference applications and documentation to take the strain off your own technical team.

How do you deal with multiple APIs?

When you have to work with multiple APIs it can get quite difficult. One way to deal with this is for your development team to create separate software libraries to interact with each API. That way, when they need to change the way they work with one API it doesn’t affect any of the other software they are working with.

What does ‘good’ look like in the world of APIs?

A good API will help your development team by including many of the following features:
Follows open standards (e.g. REST). These patterns are already familiar to developers and make working with the API simpler.

Granular access – providing clear granular access to different parts of the API also makes life easier. Different customers have different requirements and not all elements of an API are required by all customers.

Clear error messages – working with APIs is hard if error messages aren’t clear. Receiving a clear, detailed and descriptive error when something goes wrong makes it much easier for a developer to work out what they might need to change in order to work with the API successfully.

Multiple input and output formats (or language agnostic). Not all systems “talk” the same language. A multiple input format allows existing systems to be integrated with an API more easily.

High availability – This is especially important with business-critical APIs. The API is only of use to a customer when it is available. This means that even under heavy load the API should always be available for use.

High performance – A slow API means processes are slow for the end user. It also means that the server(s) handling the API requests can become overloaded more easily. The faster an API can perform operations the better.

Good documentation – The more detailed the documentation the better for developers. Interactive documentation is even better. This lets the developer try out the API and see the requests and responses before having to write a line of code.

Versioned – one potential pitfall with APIs is that they can be hard for the developers to change. Once an API is in use by clients the definitions of the API cannot be changed without every client potentially having to change their implementation. A good API will avoid this pitfall by using versioning. This means that when a change to an API is required a new version is made available to allow API users to transition to the new API in their own time, without any downtime.

What are the consequences of poor quality APIs?

If APIs are hard to use there might not be a guarantee that your data is accurate or up to date. The whole purpose of an API is to allow the exchange of data, but with a bad API you can’t necessarily guarantee that the data you have sent is correct, or the data you are receiving is accurate.

With business-critical APIs this can be the difference between a high performance business and a less successful one.

If an API that’s responsible for keeping orders flowing through a warehouse goes down, companies risk thousands of orders stacking up, dozens of warehouse operatives standing idle and numerous customers left waiting for their deliveries to arrive.

If an API is poorly documented or badly written your development team will have to invest significantly more time up front in order to be able to work with the API. This not only increases the time taken before a working integration is ready, but it can also drastically affect costs.

What do I need to think about when comparing software providers?

Is their API compatible with your current systems?

How much development time is required to set up? (SOAP, for example, can require more set up time)

How much resource will they offer for maintenance? SOAP is older so takes more effort to maintain and update.

Also, ask to see their software developer’s kit – this will show you how much of a head start they’ve given you. It’s a short cut kit and should mean that a lot of the hard work has already been done.

About the Electio API

We’re very proud of our own Electio API and here’s why:

• It is brand new, having been developed over the last 18 months. This means it has been built using all of the latest best practice and isn’t encumbered with a legacy platform that has had bits bolted on
• We’ve invested over £2m in bringing it to market, mainly through hiring tech superstars
• It is a simple REST API so very easy to use and integrate with
• It’s also language agnostic so it won’t matter what language your developers already programme in
• We chose Microsoft Azure as our hosting partner to ensure high levels of availability with automated redundancy and failover resilience.
• Its architecture has been designed for scalability - we can maintain response speeds of milliseconds even at times of heavy load, such as Black Friday.
• We challenge you to find a better SDK in our industry!

Want to know more about Electio’s API?

Give us a call on 03300 555 284