Some people describe APIs (Application Programming Interfaces) as the glue holding different software systems together.
A better analogy would be that of a plug and a socket.
Let’s say you want to join up two systems: a product catalogue (www.ProdCat.com) and a social media system (www.SocMed.com). The product catalogue can hold a range of different types of products, such as courses, books, videos. In fact, anything that has a title, a description, maybe a picture, and some categorizing information, like topics or “tags”.
The social media system simply allows users to post ideas and then tag them with topics.
The providers of the product catalog publish a description of their API. This will be a document that describes the locations of the different connection points, the purpose of each connection and how it should be used. Some of those connectors are designed to enable data to be retrieved, and some allow data to be sent.
The provider of the social media system then has to create a “plug” that can make use of those connectors; sending and receiving data to and from the product catalogue.
At its simplest, the social media system can send a request to the product catalogue which asks for the whole catalogue. Something like:
http://www.ProdCat.com/<span style="color: red;">GetCatalogue</span>
In this case, the product catalogue, assuming it has a connection called GetCatalogue, would respond with file containing all the information about all the products.
The file sent by the product catalogue will be in a set format, as described in the API documentation. Most APIs use either XML or JSON to structure the data. This means that developers will know exactly where to find each piece of data, and can thus write programmes to work through the file and process it.
With the catalogue file, a developer working on the social media system can create a page within her system that displays product information from the product catalogue system.
Exactly how that information is displayed, sorted and filtered is entirely up to the social media system developer. Once they’ve got the catalogue data, they can do with it what they wish.
Remember that this isn’t a one-off process. The catalogue information can be retrieved as often as you like. However, many systems with published APIs will set a limit on how many retrievals can be made in a certain time. This is why it’s often good practice, when building a connector to an API, to “cache” (temporarily store) data when it’s retrieved.
Usually you wouldn’t want to download all the data provided by an API, but just a much smaller subset. For example, you might want to only display the products that have categories that are similar to the tags on a particular social media posts. End users would then see a list of relevant products alongside the posts.
If I was to retrieve the whole catalogue every time, I’d be using, and wasting, a lot of bandwidth. So most APIs will allow you to filter the data at source.
If I had a post tagged “leadership”, then I only want to retrieve products categorised under “leadership”. In this case, the call to the product catalogue might look like:
http://www.ProdCat.com/GetCatalogue?<span style="color: red;">category=leadership</span>
Multiple conditions can be set in the same call just by joining them together with “&”. For example:
http://www.ProdCat.com/GetCatalogue?category=leadership<span style="color: red;">&image=true</span>
Assuming the API understands the query, this would hopefully return a file containing all the products in the leadership category which have an image.
So, I’ve explored how I get data out of a system and display it to your end users. What if I want my users to be able to interact with the data; like buy a product or write a comment against it?
Assuming you’re working with an API that can receive data as well as send it, you’ll probably use a connector something like:
Breaking this down, I have a connector called PutComment, which can accept the following types of information:
So, in this case, the user (called Mark) has entered a comment (“Great product”) in a form on the social networking system, which was displaying details about a particular product (with the id: abc1234).
This information was passed back to the product catalogue as a set of parameters for the PutComment connector.
Obviously, sending data between applications can get pretty complex pretty quickly as the two systems become more and more tightly integrated.
It’s always a good idea to map out which system holds which data, and the “triggers” that will prompt data being moved between them. Without careful preparation and definition it can easily become very muddled.
My advice is to start as simple as possible, and plan to make incremental enhancements based on user feedback.
To get the best out of an API you need three things:
Although I am not a developer myself, I can help you to understand and document your requirements, talk to your system providers, design solutions for developers to take forward, then source the developers and manage the project from start to finish.
Although these can often be complex projects, I will work on your behalf to simplify the process and translate your requirements into finished products with real benefits for your end-users.
Posted: 12 June 2013