Tools have always defined how much humans can get out of their environment be that the simple stone axe, ceramic bowl all the way through to complex machinery externally powered. Today it’s all about computation and the transfer of information notably via the Internet which states the rules or protocols of transferring information be that a simple web page via the World Wide Web (now simplified to the Web or plain Internet) or email via traditionally named post office protocol (POP) or Simple Mail Transfer Protocol (SMTP). Which every way the information gets moved and stored it’s vital to understand some of the basics in order to understand how to effectively use the technology.

One of the things you may have heard of or could come across is the need for an API or an Application Programming Interface. You may hear it in the same instance that a car mechanic tells you that you need a new a set of new bushes on your car which makes little sense in the English language. But fear not APIs are not that tricky if you have the basics and from there you can build and test your understanding.

At your defined service

An API is a defined way in which you can get information from a computer across the internet in a similar way you could order food from a waiter or even a menu card. I’ll go into more detail later but a quick aside on why this is so important as you may be wondering why this is a big deal because computers share information all the time; when I press print doesn’t the printer talk to the computer – what’s so special? That doesn’t have an API does it?

Well in the age of information you are dealing with a couple of challenges and one of those is speed. If you can be the first in the world based on information travelling close to the speed of light then there’s money there especially in markets where price and availability are important. Another reason is latency or the time it takes between asking for something and then getting a response (not necessarily an answer). APIs allow the world to connect to an information store and see what’s in it at a specific time to allow you to do something about it at the time of the request. The alternative and the old way of doing things was to ask for everything or ask for something specific that would have to search for everything. With an API you can be very specific on what you share which speeds up the response rate.

The other advantage of this lean approach to information sharing is that it can show your customers the information you have so they can use it or potentially use it in the future. For example if you are thinking about setting up a cool application that tells people where the cheapest bread is in area you may take information from bakeries in the area on their stock levels and combine this with a mapping service that can tell a user how far they are from a location. This way the bakery should get more trade and the mapping company gets more information about people travelling at certain times of the day that it can then sell on (perhaps back to the bakery) to help other businesses. Importantly as APIs are defined in how they are called and how they respond they are more secure than other methods that allow for a wider range of query.

One thing to highlight at this point – calls from and to APIs do not come from human being like you and me; instead they come from other computer services that are triggered to do something under a certain condition or input. This is handy to remember when we are thinking about designing an API.

Types of API

A body will stay at REST until called

There are a few types of API out there but the most common and the one that you are most likely to come across is a REST API. REST sounds nice and chilled and it pretty much is. It stands for Representational State Transfer (REST) and it does what is says – it returns the state information from the server at the time of the call. It is said to be stateless as the information returned has no other information other than what was requested. The simplest of the REST API means it is quick to use and modify as it’s a style rather than a stricter protocol. REST APIs are used from serving up this webpage to take credit card payments securely. The chances are you will come across the phrase “we have an API for that” in which case it is likely to be a REST API.

Keeping it clean with SOAP

The other API you may hear is SOAP which functions like REST but is very different under the hood. SOAP stands for Simple Object Access Protocol which is the old timer of the Internet starting back in 1998 before smart phones and all the connected systems we all use today. SOAP is a trickier customer than the lightweight REST due to one letter – P standing for Protocol. Protocol conjures up things that must be done, complied to, enforced to work etc and that is true for SOAP – if you want to use SOAP then there are things you have to do and work with. One of the things that SOAP uses is a file format called Extensible Markup Language (XML) as in a language that can extend to contain different types of information instead of being locked down into a specific format. SOAP and XML mean that this type of API can be used in more ways than REST as REST can only use one way of getting across the Internet via the HyperText Transfer Protocol (HTTP) which is used to transfer hypertext files like a web page that has hypertext or hyperlinks. The World Wide Web is built on top of HTTP with clients requesting information from servers via a web browser

Due to the complexity of SOAP against REST REST is the most common type of API. SOAP APIs if they could describe REST as a dirty API due to the lack of rigor or protocol. However, REST does have a “standard” which uses the same protocol for web pages (HTTP) and so the APIs are described as RESTful as the API is full or REST e.g. playful, beautiful, and helpful).

JSON and the Golden Thread

If SOAP has XML what does REST have as way of moving information around? The answer JASON. Well, that is how you pronounce it but it’s actually JSON standing for JavaScript Object Notation (so they could have gone with JASON if they weren’t such spoil sports but it is shorter to type) and is a defined format for REST APIs to use.

The JSON format is simple and less bulky than XML using far less characters to communicate as the example below shows.

XML (HTMLish)
<contact>
 <firstname>Jay</firstname>
 <lastname>Pea</lastname>
 <age>45</age>
 <address>
  <buildingaddress>1 Oak Drive</buildingaddress>
   <town>London</town>
   <postcode>W1A AAA</postcode>

  </address>
</contact>

JSON (JavaScriptish)
{
 "firstName": "Jay",
 "lastName": "Pea",
 "age":45,
 "address":
  {
   "buildingAddress": "1 Oak Drive",
   "town": "London",
   "postCode": "W1A 1AA"
   }
}
    

Who goes there? Authentication

When you open a web browser and go to a website of your interest it’s simple – the page loads. With APIs you need to get permission to get the information you need via two authentication methods:

1) Basic Auth authenticates you using via a username and password – super simple. However that username and password is passed over the Internet in plain and readable text – not very secure. We can add security by encrypting the message using HTTPS instead of HTTP which does not encrypt data before it is transferred. The S of HTTPS stands for Security where another layer of security called Secure Socket Layer (SSL) is added. HTTPS scrambles the message between the browser or application to the server and back again so that if someone if sniffing through your internet traffic they won’t be able to work out what is being sent (this is quiet easy as a crafty villain can put them in between you and the information you are interested in like like a WiFi connection). This additional security may sound like Basic Auth is ok to use but it has one other draw back and that is sharing security information with a third party

Due to this reason Basic Auth is only good for authenticating against an API that is transmitting public, non-sensitive information of which there are many.

2) OAuth