A REALLY USEFUL GUIDE TO APIs

(‘{“API 101”}’)
No, it’s not a type of beer, APIs, also known as Application Programme(ing) Interfaces, in their simplest form, allow applications to communicate with other applications. This said, there is a lot more to them once you explore their capabilities further. APIs are slowly creeping into every aspect of our personal, and business ecosystems, often even without us even realising. If you have ever surfed the web, and use a smartphone, then in all likelihood, you have already come across multiple APIs.

Who uses APIs?

Have you ever used the app on your phone to check your email? The weather app? or perhaps scrolled through endless posts/pictures on Reddit or Pinterest? Well, these are all common examples of APIs. amongst the vast ocean of APIs around there are also more subtle ones around that may not be so obvious.

Ok, how does it all work?

Imagine a waiter in a restaurant. You, the customer, are sitting at the table with a menu of choices to order from, and the kitchen is the provider who will fulfil your order.

You need a link to communicate your order to the kitchen and then to deliver your food back to your table. It can’t be the chef because she’s cooking in the kitchen. You need something to connect the customer who’s ordering food and the chef who prepares it. That’s where the waiter — or the API — enters the picture.

The waiter takes your order, delivers it to the kitchen, telling the kitchen what to do. It then delivers the response, in this case, the food, back to you. Moreover, if it’s designed correctly, hopefully, your order won’t crash!

But what do they look like in the real world?

Ever booked a holiday online? Once you’ve chosen from the plethora of sites available, you have a menu of options to choose from. You choose a departure city and date, a return city and date, cabin class, etc…

To book, you need to communicate with the airline’s website in order to access their database and check if any seats are available on those dates, and what the cost might be, flight time, etc.

You need access to that information from the airline’s database, whether you’re interacting with it from the website or an online travel service that aggregates information from multiple airlines. Alternatively, In any case, you need to get the information, and so the application must interact with the airline’s API, giving it access to the airline’s data.

The API is the interface that, like your helpful waiter, runs and delivers the data from the application you’re using to the airline’s systems over the Internet. It also then takes the airline’s response to your request and delivers right back to the travel application you’re using. Moreover, through each step of the process, it facilitates the interaction between the application and the airline’s systems – from seat selection to payment and booking.

How do you make an API?

Like building anything, there are several steps, unexpected challenges and loads of planning required.

Plan
o Who is it for?
o What product will you make available?
o What does it need to do?
o Their use cases?
o What tech will they be using?
o What type are you building? SOAP/RPC/REST…
o Scalability and longevity
o Authentication?
o Security/GDPR

Build

You’ve spent hours, days, weeks, months perfecting the perfect design for your API and now it’s finally time to start building. When building a house, it’s important to have the right team for your project, as well as the right tools. The same goes for building an API. There are a number of tools that can help you build out your API in an easy and efficient way.

o Get the right tools for the job
o Project management tools
o CLI/code editor
o Test environment
o Debugging tools
o OS and browser compatibility

Inspect

This step is crucial to success. It’s very important that your project, whether it is a home or an API, be tested and inspected for bugs and defects. When working with a home inspection, there are usually a set of requirements that are needed to pass an inspection.

There are plenty of companies out there who don’t test their APIs. Similarly, we assume building inspectors are supposed to make sure construction on a new home is on point. But that doesn’t always happen in reality.
There are pros and cons to creating something that is just “good enough” versus “perfect.” In software, shipping a first product that is “good enough” is a perfectly acceptable workflow for some, but you should make sure that it’s “good enough” to be useable.

Document

Writing documentation should take the least amount of time and efforts, and should minimize the maintenance.
You have to find a good way to write the least amount of textual explanations for your API, which yields the highest value of practical guidelines for the user of the documentation. Some things to consider, are:

• Examples
o Include some sample request objects, or some code samples, etc.

• Descriptions
o Requests, folders, collections

• Portable
o This is when the auto-generated code can be either displayed as a page or an embedded window of information. It also means that the result of your documentation is re-usable.

• Deployment
o This really depends on the personal preferences on how to manage this part of the process – Possible solutions include, direct from your repository using GH pages or Heroku.

Why Document APIs?

Among all the phases of the API lifecycle, documentation is probably the area showing the most growth. This is especially true with the tooling ecosystem around documentation. It’s interesting to note this trend since documentation is traditionally something that developers paid little attention to when launching code. In fact, it’s much easier to implement code, than is it to write good documentation.
But this is because of its direct impact on adoption and usage. You can have the best, most functional product, but no one will use it if they don’t know how to. Documentation is the foundation for good Developer Experience.

So, you have your website or APP, how do you now use someone else’s API?

I used to work in customer support at a technology company where API connections that pulled user data from other programs were integral to the product. When I would explain to customers why we couldn’t access a particular piece of data, developers would often recommend the answer, “It’s not available over the API.”

At the time, I figured an API was like a USB port, and by connecting to that port, we would have access to everything in another program. Turns out, I was wrong.

An API will not give you all of a program’s information or code, because; what would stop you from copying all of the code? Instead, an API provides you with data its programmers have made available to outside users. Even so, you have to know the language and ask the right questions in order to do anything with this data.
When the code for an API is written, the programmers will expose a part of the code, called an ‘endpoint’.

These are subsequently used to build URLs, to request the data. The URLs will then return text that is designed for a computer to read, usually in Extensible Mark-up Language (XML) or more recently, most programmers prefer to use JavaScript Object Notation (JSON).

JSON: Sometimes referred to as the ‘Fat-Free alternative to XML, an example as to why can be seen below.

Architecture of an API

APIs consist of three parts:

I. User: the person who makes a request
II. Client: the computer that sends the request to the server
III. Server: the computer that responds to the request

Confused? Let’s use a real example: an address book.

Back in the analogue days, you’d receive a copy of the Yellow Pages phone book, which listed every person in your town by name and address, in alphabetical order. If you needed a friend’s address, you could look them up by the last name, find the address, then look up their street on the maps included in the back.

This was a limited amount of information, and it took a long time to access. Now, through the magic of technology, all of that information can be found in a database.

Let’s build a database containing the Yellow Pages for a fictional town called Springfield. The folks at Springfield Yellow Pages decided that when they built their database, they would create a few categories of information with nested data underneath. These are our endpoints, and they’ll include all the information the API will release to an outside user.

Here are the endpoints listed in the documentation for Springfield Yellow Pages:

 /names
o /first_name, /last_name
 /addresses
o /street_address, /email_address/
 /phones
o /home_phone, /mobile_phone

Obviously, this isn’t all the information that could be collected about a person. Even if Springfield Yellow Pages gathered more private information about the Springfield residents (like birthdates and ID/ National Insurance numbers), this data wouldn’t be available to outside programmers/users without knowing the language of those endpoints or the required permissions as per applicable Data Protection Regulations.

These endpoints tell you the language you must use to request information from the database. Should you want a list of all of the people in Springfield with the last name Smith, you could do one of two things:

1. Make a URL request in a browser for that information. This uses your internet browser as the client, and you will get back a text document in coding language to sort through (remember the XML/JSON example above). That URL might look something like this: http://api.happyville_wp.com/names?last_name=smith

2. Use a program that requests the information and translates it into a usable form. You can code your own program or use a ready-made HTTP client.

The first option is great for making simple requests with only a few responses (all of the folks in a Happyville with the last name Xarlax, for example — I’m pretty sure there are only six households with this name in Happyville). The second option requires more coding fluency, but is great for programmers who want to use the database of another program to enhance their own apps.

Many companies use the open APIs from larger companies like Google and Facebook to access data that might not otherwise be available. APIs, in this case, significantly lower the barriers to entry for smaller companies that would otherwise have to compile their own data.