Discussions and content on the subject of APIs tends to be aimed at developers who are already familiar with the concepts and terminologies. For everybody else, here’s a straight forward guide to what integration is, how an API works and some of the key concepts you’ll need to understand.
Why do we talk about APIs at all?
It’s all about connection. As a software developer, allowing other developers to connect their applications with yours is an appealing concept. Collaboration in this way presents a huge potential for the rapid development of new products and services and the expansion of new markets. As an application user, connecting complimentary applications is one of the most valuable steps you can take for your business. It’s a discussion in itself but take a detour back to last week’s blog post (the hidden value in integrated data) if you want to delve deeper into some of the main benefits of connected applications.
Let’s start at the beginning.
What is an API?
The API is the ‘digital plumbing’ which makes connected applications possible. API stands for ‘Application Programming Interface’. As the name suggests it’s a programming interface between otherwise separate applications that allows each application to connect, communicate and share information with the other. The beauty of integration is that data isn’t merged or assembled into a single place. Instead it becomes mobile across the connected applications, maintaining the intended purpose of each whilst adding value to both.
You might think of an API process as a set of computational rules (the method) and software tools (the practical bits) which manage what, when and how information is shared between each application. The information itself is often referred to as the ‘resource’ and the connectivity which is achieved is commonly called ‘integration’.
Sign-Up.to’s API is called the Permission Marketing API or PMAPI for short.
Applications – what can be connected?
There are many forms of API and many different applications that can be connected, but for our purposes we’ll assume that the applications to connect are an email marketing application (like Sign-Up.to) and other common business applications which potentially share similar and useful data. Again, there are many, but applications like CRM (Customer Relationship Management), eCommerce and booking or reservation systems are probably the most common. Here are some you may be familiar with.
It doesn’t have to be, but integration is generally a two-way process. In the case of a Customer Relationship Management system, the customer details which reside in the CRM are potentially valuable in refining and targeting your email marketing campaigns, and the intelligence gained your email marketing also has value in updating your customer records. After all, who’s engaging with your marketing is valuable information for your Sales team.
How does an API work?
To be slightly more specific, the API is a part of an application where the developers have intentionally made sections of the programming code publicly exposed – notably the areas associated with the sending and receiving of information. You may see these locations referred to as ‘endpoints’ – they’re the dangling wires from which external connections can be made and through which identified resources can be shared. The more endpoints that are exposed, the more extensive the nature of the integration can be.
This means that, given the open endpoints, the process rules and the tools to do it, developers can readily create or adapt other applications to connect together.
Why do it in this way?
It’s a good question. Some public domain applications are built using completely open programming methods – Linux applications are a good example. This openness allows source code to be seen and created potentially by anyone. However, while many commercial developers are keen to have others integrate with their applications, exposing their entire application code in this way may not be desirable. The API therefore exposes (that is, extends beyond the secure firewall) only the parts of the application code which are needed in order for others to find and make the connections. Taking this approach meets the objectives of easy integration while maintaining the in-house quality and security of the application itself.
Some concepts to start off with
API development is full of jargon and acronyms, so here are couple of concepts and definitions to get us started.
The first, and probably most familiar, is HTTP or Hypertext Transfer Protocol. HTTP is the set of rules (sometimes thought of as the ‘digital etiquette’) we all use to transfer web based information. Anyone using web browsing is essentially using HTTP (or HTTPS) to make and receive their online requests. These rules or protocol set out a mutually agreed framework for the conversation, allowing each application to communicate in a meaningful way. Without this any attempted communication would just be chaos.
API developers will also talk about REST or RESTful processes. REST stands for Representational State Transfer. We don’t need to go into too much detail but essentially REST applies a common definition and standard of API development for web based applications. It’s widely used.
REST’s major feature (and the main difference from other standards you may come across, like SOAP for example) is that REST is primarily concerned with ‘things’ – that is information, data or to give the proper terminology, resources. In a RESTful process this ‘stuff’ is referred to as ‘nouns’. We’ll see later how REST therefore also uses ‘verbs’ in order to process instructions as to what to do with these nouns.
A fully RESTful API has a number of (actually six) specific compliances to meet. However, while an overall RESTful approach is common it’s not entirely necessary to have 100% compliance with the REST principles in order to be considered a RESTful API and to still achieve the main benefits.
Since REST uses the same techniques as are used to manipulate web content it means that it’s widely understood and used by the developer community, allowing the rapid creation of APIs. It may sound complicated but simplicity is actually a fundamental philosophy of RESTful development.
Servers and Clients, Requests and Responses
With integrated systems the two sides of the connected applications are called the ‘Server’ (the side where the host application, and the host API sits) and the ‘Client’ (the side where the connected application and it’s end-user, or consumer, sits.
In general, the 2-way communication between the Client and the Server takes the form of ‘requests’ (or sends) where information is asked for, and ‘responses’ (or returns) where the requested information is supplied. For example, your email marketing application may request the latest customer details from your CRM system. On receipt of the instruction, your CRM system duly extracts and returns the data so it can be used in your next email marketing campaign.
It’s a little detail, but the request to transfer information generally needs access to the four key ingredients.
Firstly the URL, the ‘Uniform Resource Locator’ (it’s a subset of the URI, the ‘Uniform Resource Identifier’). This describes what the information or resource ‘is’ and where it can be found – it’s the ‘noun’ part as mentioned above. Secondly, the method by which transfer will be carried out. This is where the ‘verbs’ mentioned earlier come in – these are instructions like ‘Get’, ‘Put’ and ‘Delete’ which instruct what action is to be taken, and what the resulting consequence will be. The final two pieces are the header and the body of the information. These comprise the information itself (the body) and any other qualifying ‘meta’ information (in the header) which is going to be useful, for example device type, so that the resource can be transferred in a meaningful way.
Creating an instruction
The process of making API resource requests (sometimes called ‘calls’) is where the ‘verbs’ come in. There are many verbs but the four most common, and possibly the most obvious are ‘Get’, ‘Put’, ‘Post’ and ‘Delete’.
As it suggests, ‘Get’ is a request to retrieve or extract information from the Server application and supply it to the Client. Similarly, ‘Put’ returns existing information along with any updated attributes. ‘Post’ is similar to Put except that it refers to the return of new information only (that is data which doesn’t currently exist on the server). And ‘Delete’ is the instruction to remove an existing resource.
Two other terms which you may see in relation to these instructions are ‘safe’ and ‘indempotent’. So to explain…
‘Safe’ means that the instruction or operation cannot change an existing resource. It’s merely a transfer of a resource in its current state. Unsafe is of course the opposite, having the ability to change or destroy existing resources (‘Delete’ is therefore an unsafe instruction as it changes the nature of the resource in question).
‘Indempotent’ is a mathematical property of an operation which means that the same instruction, issued many times will always return the same result, in fact the same result as it being issued as the single original instruction. Zero plus zero plus zero etc is indempotent – it’s always zero. The effect with APIs is slightly more subtle but has important consequences for data integrity. The instruction to ‘Put’ is indempotent since multiple puts of the same resource will have the same effect as the original instruction. However the instruction to ‘Post’ (new data) is neither safe nor indempotent – the instruction both changes the resource and has a different result each time.
Formatting – how the data is
How do you know what resulting effect an API instruction has had? That’s done by looking at the HTTP ‘status code’. Each status code tells you the end result of the operation – successful or otherwise. By the way, the consistent use of status codes is an important part of RESTful API design. There are lots but some of the most common status codes are:
200 OK – this is generally associated with the Get verb signifying that the operation has been successful.
201 CREATED – this is returned as a result of Post and Put (also Patch) indicating the returned resource.
204 NO CONTENT – instructions to delete will result in this status, indicating that the resource no longer exists.
There are also three error status codes you may come across, namely 400 INVALID REQUEST, 404 NOT FOUND and 500 INTERNAL SERVER ERROR. You may have seen these when browsing web pages.
Authorisation – who can access the API
I appreciate that we’re skipping out a lot of other stuff here, but there’s one final thing to discuss. That’s controlling who can use the API – developers call it ‘Authorisation’.
Once the data transfer process is in place, it’s likely that both clients and servers will want to exert some sort of management control over who can access the API and make and receive requests. Secure authorisation isn’t essential, but assuming it’s desirable then there are two (ish) main ways of granting access and authenticating approved users.
‘Hash’ authorisation works on the provision of a digital ID which acts as an authentication signature. Once it’s set up, API requests can be made by any ID user or person who is delegated the details of the ID. The ‘token’ method is similar except like a web session session cookie it generates an authenticated use to a specific user. This allows a more granular level of user control and increased level of security.
‘OAuth’ is an open standard which allows secure access to places like secure websites (for example when you log into your Facebook account). Used with APIs it allows the server to manage individual and secure levels of access. In that respect it’s often the preferred method of API authorisation.
Summary – API in a nutshell
So an API is a Application Programming Interface that allows complimentary but otherwise separate applications to communicate and share data. Transfer is generally between the host application (the Server) and the consumer application (the Client). The API process uses a number of protocols (like HTTP) and standards (REST) which ensure quality and consistency. RESTful API’s are built around tangible data resources (nouns) which are identified and located using their URL/URI. The specific nature of the resources relies on formatting tools like XML and JSON. The transfer of resources between connected applications is achieved using calls (or verbs) like Get, Post and Put, and each operation results in a status code which confirms the outcome of the operation. Finally, an authorisation process like Hash or OAuth is used to control who has access to the API and can make requests of it.
You’ll find that many applications for which integration is valuable have a number of their most common integrations built in. Explore the integrations section of Sign-Up.to and amongst others you’ll find pre-built integrations for CRM applications like Salesforce.com and Microsoft Dynamics and the eCommerce applications Shopify and Magento. These are already set up so all you have to do is switch them on and do a little configuration of how you want them to work. As applications are developed either by ourselves or our Partners, new pre-built integrations are being added all the time.
Sign-Up.to also allows users direct access to the API itself. This allows users to connect more specialist applications which are not yet included or those which have been custom built in-house for a specific purpose. With a little IT knowledge and the documentation provided, using the API to make new connections is relatively easy. Our Integrations Team also offer this as a service for those who prefer to leave this to the experts.
The Sign-Up.to API has an additional use. Since it’s such a handy framework for creating connections it’s actually the tool that we use ourselves, behind the scenes, to build both new generally available and custom integrations.