What is an API? How do they work? — In non-technical terms.

APIs are like lego blocks, allowing developers to compose them in ways that make sense to their specific use cases. A banking API can be used by developers to create an online shop and by other developers a lending app.

Each lego block represents a certain capability that is being offered by the API publisher.

Here’s another analogy for what an API is:

We shared this with our developers and they helped us unpack it further. Here’s what we learned!

APIs are like a restaurant menu

APIs give developers options for what they can do with a piece of software. For example, an API belonging to an online shopping system could let developers do a range of things:

• Create products
• Retrieve products
• Update a product’s details
• Add pricing
• Create a name for the shop
• Retrieve the shop’s name

And the list goes on…

Let’s take a look at an example of how a developer would go about creating a product:

POST myOnlineShop.com/api/product/
{
   productName: "BatMobile",
   price:       5000,
   currency:    "USD"
}

Let’s break it down:

POST is the equivalent of saying ‘Go ahead and create XYZ’. So in the example above, we’re saying ‘Go ahead and create a product’.

And /api/product is the ‘API Call’, what they’re requesting from the Online Shop menu. Again, POST myOnlineShop.com/api/product is the same as saying Create a product.

But how do we tell it what to create?

The section beneath { productName: 'Bat Mobile', price: 5000, currency: 'USD' } is the specific details of what developers are expecting from the waiter (the API). This is also called ‘the request body’. So in this case, the request is to Create a Product and set the product’s name to “Bat Mobile” and price to $5,000 USD.

How do developers know what an API does?

On the surface, it seems magical that a developer can look at POST myOnlineShop.com/api/product and a) know it means to create a product b) know to specify a product name, price and currency. How do they know this for sure?

Documentation!

APIs are usually well documented (well, they should be). So documentation for the API we saw earlier could look something like this:

Create a new product:
POST myOnlineShop.com/api/product/
This command accepts a productName, price and currency as part of the call. For example { productName: 'Bat Cape', price: 200, currency: 'USD' }
Retrieve an existing product:
GET myOnlineShop.com/api/product/{productName}
This call accepts a productName identifier to retrieve a product. For example GET myOnlineShop.com/api/product/BatMobile
Delete an existing product:
DELETE myOnlineShop.com/api/product/{productName}
This call accepts a productName identifier to delete an individual product. For example GET myOnlineShop.com/api/product/BatMobile
Suggest upsells for an existing product:
PUT myOnlineShop.com/api/product/upsell
This call accepts a productName and link as part of the call. For example { productName: 'Bat Laser', link: 'myOnlineShop.com/products/laser' }

With documentation, a developer can assess:

1. What the API offers (in this case, the Online Shopping System).
2. How easy is it to use.
3. Whether it has specific features (for example, can we set up promotional pricing out of the box).

Different APIs can offer the same thing differently

Not every online shop lets developers create products in the same way. The first example allowed developers to create products in this way:

My Online Shop Documentation
POST myOnlineShop.com/api/product/
This command accepts a productName, price and currency as part of the call. For example { productName: 'Bat Cape', price: 200, currency: 'USD' }
POST myOnlineShop.com/api/product/
{
   productName: "BatMobile",
   price:       5000,
   currency:    "USD"
}

But let’s take a look at another store, “my Other Online Shopping System”. It expects developers to create products using this approach:

My OTHER Online Shop Documentation
POST myOtherOnlineShop.com/api/item/
This command accepts a tittle and amount as part of the call. For example { title: 'Bat Cape', amount: '200' }

So unlike the first example, here’s how a developer would create their product:

POST myOtherOnlineShop.com/api/item/
{
   title: "BatMobile",
   amount: 5000
}

Both shopping APIs allow developers to create products, but notice the developer makes a different call to do the same thing:

POST /api/item compared to the first example POST /api/product.

This is purely a matter of API creators offering capabilities in their own way. Using the restaurant analogy: Two restaurants could offer poached eggs… one calls it ‘Poached Eggs on Toast’, the other calls it ‘The Runny Toast’. Both refer to the same thing.

Further, the request body is different in each case: My Online Shop specified the name of our new product using { productName: 'Bat Mobile' } and in My Other Online Shop the request body was { title: 'Bat Mobile' }. Also notice My Online Shop allows users to specify a specific currency, whereas this is not supported in My Other Online Shop.

The difference is purely a matter of how each software company chose to design its API. But it's these differences that can lead developers choosing one software over another. Developers might prefer My Online Shop’s API because it is more “semantic” than the second API and that it supports multiple currencies.

APIs are super descriptive

APIs are super descriptive. They not only tell developers what they can create, but also what they can retrieve (these are referred to as GET requests) and also what they can update (PUTrequests) and Delete (DELETErequests).

So for example, now that we’ve created our Bat Mobile. Let’s assume we want to include recommended upsells:

PUT myOnlineShop.com/api/product/BatMobile/upsell
{
   productName: "Bulletproof Windows"
   link:        "myOnlineshop.com/products/bulletProofWindows
}

Notice that we used the POST myOnlineShop.com/api/{productName}/upsell schema from the API Documentation to do this.

A new way to look at websites

If you haven’t figured this out already: This is a big deal! The next time you look at a website, you’ve now got a sense of how they’re composed.

Let’s take a look at our fictitious “My Online Shop” for example. When we load up a page, we might get something like this:

A new way to look at websites! Most pages are composed of APIs.

At a glance, it just looks like a page with text, images and text boxes. But each of those elements is powered by some sort of API call. We’ve included some examples, see if you can fill in the blanks for some of the other elements.

What this means for business people

Businesses are increasingly powered by APIs. Whether it’s to run your payment system, a hospital, warehouses or an entire Supply Chains: there’s guaranteed to be APIs powering processes and automation.

For business users and leaders, it becomes incredibly important to:

• Ensure you’ve got the right people managing APIs your business depends on or even more, APIs you expose to customers. This means two things specifically:
• Be aware that poorly designed APIs can single-handedly destroy your customers’ experience. This is absolutely the case if you’re in the business of exposing APIs to technical customers.
• Encourage teams to make APIs meaningful. Looking at an API library should convey meaning, even to non-technical people. This helps ensure you don’t have people leave the company and end up with teams paralysed by fear of improving systems because they don’t understand what’s going on.

How Sky Ledge Helps

Sky Ledge helps businesses see their assets, people and notifications in realtime. People think of us as enabling “actionable insights”. We do this by making it incredibly easy to connect into your existing systems (and APIs!) to see what’s happening, where and more importantly take action.

Our customers usually need to :

• Get a visualisation of what’s happening or,
• Go beyond visualisation and receive alerts or,
• Go beyond receiving alerts and automate responses or,
• Share insights with different stakeholders in ways that are relevant to them.

Sky Ledge is beautiful, secure and easy to integrate with.

We love working on customer challenges. Whether you’re in Resources, Utilities, Supply Chain or Government: we can help.

Learn more at skyledge.com and reach out direct at andrew@skyledge.com or sales@skyledge.com for a chat!

We hope this was useful and we’d love to hear from you!