In this article, we provide a comprehensive overview of APIs, covering everything from their uses and applications to real-world examples and alternative solutions
If you’ve clicked on this article because you’re curious to know what an API is, or how an API works, you might be surprised to discover that, in doing so, you have in fact, just triggered a request using an API.
APIs are all around us, quietly facilitating the digital dance of data and functionality. Whether you're using a weather app on your smartphone, sharing a tweet on social media, or ordering your shopping online, APIs are the unsung heroes making it all happen.
So, if you’d like to know what’s going on behind the scenes, don’t go anywhere.
In this week’s blog, we’ll be covering the following topics:
Let’s dive straight in.
“API” is a simple acronym that stands for Application Programming Interface. In the domain of software and app development, we use it to describe a set of rules or code that allow software programs and services to interact with one another.
Unlike a UI (user interface) which is designed for interactions between humans and computers, an API is created so that machines can communicate with one another.
In our last article on headless commerce, we used a straightforward restaurant analogy to explain how our API works. Here it is in the form of a simple diagram.
In the diagram, our customer (app or client) chooses their items from the menu and then gives their order to the waiter (API). Next, the waiter writes down the order (request) and delivers it to the chefs in the kitchen (back-end) before they prepare the food and deliver it back to the customer (response).
This is just how APIs work within the realm of software development. The API takes our data request from our app, delivers it to the back-end, and then returns it to the user's device in a readable, user-friendly format.
When we use the term API, we’re most often referring to web APIs, which started to emerge at the beginning of the 21st century.
However, the concept of using APIs came about long before the dawn of the internet, when British computer scientists Maurice Wilkes and David Wheeler created a computer named EDSAC.
Developed in the 1940s, EDSAC was one of the first stored-program computers capable of holding and executing programs in electronic memory — a fundamental characteristic of our modern-day machines.
Wilkes and Wheeler’s computer used subroutines (codes designed to perform a particular task) and a catalogue/documentation system that could build complex computer instructions from simpler, micro-instructions.
What does this have to do with APIs?
Well, the concept of breaking complex tasks into smaller, reusable components which can be called upon when needed, is what forms the foundation of APIs. With APIs, pre-defined functions or methods are made available for developers to integrate into their software, promoting modularity and reusability, just as subroutines did in early computing.
Even though the term "API" technically didn't exist back then, this idea established the principles of modularity and standardised interactions that underlie contemporary API design.
As we touched upon at the start, Web APIs are the reason that you’re reading this article right now. In fact, every time you access a website or a mobile app, you're engaging with web APIs, whether you realise it or not.
So, let's break down how you got here.
Firstly, when you clicked on this article, your device sent a request to a server somewhere out there on the internet.
That server, which hosts this article, then received your request.
Finally, said server used a web API to understand your request, fetch the content you wanted, and then send it back to your device.
Et voila, now you’re here reading about APIs.
Ok, so that was a very over-simplified version of what was taking place but we’ll get into the finer details as we delve deeper into the subject.
If you use cloud-based software or analytics reporting tools, you may have come across the term “API call”.
If you don’t know what this is, don’t fret. It’s fairly straightforward.
Remember our restaurant analogy? An API call is simply the order that gets sent from our customer to the kitchen. In short, it’s another way of describing an API request.
Depending on the publications that you read, you may find that some authors choose to separate the two terms, reserving the use of the term “API call” to emphasise the action of making a request, while "API request" may be used more broadly to refer to the entire interaction, including the request and the response.
As with all web and software-related jargon, it’s not worth getting too bogged down by this.
Generally speaking, the terms are used interchangeably and normally imply the same thing.
An API call will typically include information about what is being requested, any necessary parameters, and details on how the response should be formatted.
It’s a bit like when our waiter jots down an order on a notepad. Often, they’ll use some sort of code to let the chef know that the customer has a peanut allergy or has specific dietary requirements. This code is of vital importance because it is central to constructing the API request.
Making An API Request Over The Internet
The code you use to make a request will be written in a programming language. This might be PHP, Javascript (Node.js), Python, or another alternative, and will specify several important details:
The HTTP Method
Firstly, the code you use determines the HTTP (Hypertext Transfer Protocol) method to be used in the request.
HTTP is a text-based exchange mechanism that powers the internet and is easy for both humans and computers to read. It is essentially an API built on top of TCP (Transfer Control Protocol) and relies on IP (Internet Protocol). APIs for cloud services can be implemented using HTTP or its secure encrypted version, HTTPS.
Consider a scenario where we've built an employee management system and want other applications to access the contact list. In this example, we can create an API on top of HTTPS. This is commonly known as a REST-based API - we’ll explore this in more detail later on.
There are a number of HTTP methods that we use to tell the server what to do with the data.
These are the most common:
GET: Used for retrieving data from the API.
POST: Used for sending data to the API, often for creating new records or updating existing ones.
PUT: Typically used for updating existing data.
DELETE: Used to request the removal of data from the API.
In the hypertext transfer protocol, these are simple text strings that would be formatted like “method: POST”. The vast majority of forms on the internet use the POST method and you can often see this on the html form tag itself where the method property is defined.
If we wanted to access our list of contacts, however, we might choose to use the GET method because it can be easily cached and is a simple way to retrieve a list of information.
Your API Endpoint
Your code will also specify the URL of the API's endpoint. This is the location where the request is directed. It's like providing the address of the restaurant where you want to place your order.
For example, if our EMS (Employee Management System) was “www.new-team.com” then our endpoint (or API address) could be “www.new-team.com/api/employees”.
Headers
The code may set various headers in the request. Headers contain additional information about the request, such as authentication tokens, content type, and other metadata. Again, these can be simple “key: value” text strings in HTTP and can be conveyed as parameters at the end of the URL after a question mark like “?my_info=value&other=value” or within the body of the request (which is not visible in browsers).
Data Format
Lastly, the code will determine the data format to be used for the request payload (the information included in the body of an HTTP request). This format could be JSON, XML, or another format and dictates how the data should be structured and presented in the request.
Executing the API Call
Finally, once the API call is constructed by the code, the programming language is responsible for executing the request.
The programming language sends the request to the API server over the internet and then, once the server receives it, it processes it according to the specified HTTP method and sends back a response. Just like our request, the response may also be in a structured data format, typically JSON or XML.
We thought you’d never ask!
JSON (JavaScript Object Notation) and XML (Extensible Markup Language) are both examples of data formats.
JSON is a lightweight data interchange format that's very easy for both humans and machines to read. This is what it looks like:
{
"employee": {
"id": "EMP001",
"personalDetails": {
"firstName": "John",
"lastName": "Doe",
"dob": "1990-05-15",
"address": {
"street": "123 Main St",
"city": "Anytown",
"state": "CA",
"zip": "12345"
}
},
"skills": [
"Java",
"Python",
"JavaScript",
"SQL"
],
"projects": [
{
"projectName": "Inventory Management System",
"role": "Lead Developer",
"description": "Developed a system to manage inventory efficiently.",
"technologies": [
"Java",
"Spring",
"MySQL"
]
},
{
"projectName": "Customer Relationship Management",
"role": "Software Engineer",
"description": "Implemented features for customer interactions.",
"technologies": [
"Python",
"Django",
"PostgreSQL"
]
}
]
}
}
JSON Script Example
XML, on the other hand, is a tag-based format, often used to describe, store, and transport data in a hierarchical, structured manner.
<employee> <id>EMP001</id> <personalDetails> <firstName>John</firstName> <lastName>Doe</lastName> <dob>1990-05-15</dob> <address> <street>123 Main St</street> <city>Anytown</city> <state>CA</state> <zip>12345</zip> </address> </personalDetails> <skills> <skill>Java</skill> <skill>Python</skill> <skill>JavaScript</skill> <skill>SQL</skill> </skills> <projects> <project> <projectName>Inventory Management System</projectName> <role>Lead Developer</role> <description>Developed a system to manage inventory efficiently.</description> <technologies> <technology>Java</technology> <technology>Spring</technology> <technology>MySQL</technology> </technologies> </project> <project> <projectName>Customer Relationship Management</projectName> <role>Software Engineer</role> <description>Implemented features for customer interactions.</description> <technologies> <technology>Python</technology> <technology>Django</technology> <technology>PostgreSQL</technology> </technologies> </project> </projects> </employee>
XML Script Example
In these examples, both of these formats display structured data representing information about an employee, specifically their identification, personal details, skills, and projects. However, you may have noticed that, in the second example involving XML, the script is slightly more complex and involves more instructions. This is why many developers lean toward JSON since it’s quicker to use and involves less coding.
If it helps you remember, you might choose to think of it this way:
JSON, which is pronounced like Jason (a human name) is slightly easier for humans to read and understand.
To help you put all of this into context, here is a complete raw HTTP request using the JSON format with our POST text string.
POST /api/employees HTTP/1.1
Host: www.new-team.com
Content-Type: application/json
Authorization: Bearer your_auth_token
{
"employee": {
"id": "EMP001",
"personalDetails": {
"firstName": "John",
"lastName": "Doe",
"dob": "1990-05-15",
"address": {
"street": "123 Main St",
"city": "Anytown",
"state": "CA",
"zip": "12345"
}
},
"skills": [
"Java",
"Python",
"JavaScript",
"SQL"
],
"projects": [
{
"projectName": "Inventory Management System",
"role": "Lead Developer",
"description": "Developed a system to manage inventory efficiently.",
"technologies": [
"Java",
"Spring",
"MySQL"
]
},
{
"projectName": "Customer Relationship Management",
"role": "Software Engineer",
"description": "Implemented features for customer interactions.",
"technologies": [
"Python",
"Django",
"PostgreSQL"
]
}
]
}
}
In our final example, we have demonstrated adding John Doe to the system. We can see his details in JSON format, the endpoint URL (/api/employees) and additional headers for content type and authorisation.
Now that we’ve covered API calls and how they’re structured, let’s take a look at the authorisation part of our request message.
Authorization: Bearer your_auth_token
This authorisation header is our API key.
An API key is an alphanumeric string that API developers use to maintain control over who can access and utilise their APIs. This key acts as a digital seal of approval, granting permission to those who possess it. So, when a developer creates an API for your software module, other developers can leverage it to embed your module's capabilities into their own applications.
Imagine you have crafted a module that takes a list of items and smartly pinpoints the stores offering those items at the most budget-friendly prices. Now, let's say there's an e-commerce app eager to provide its users with daily grocery bargains. They can use your API to do just that, seamlessly integrating your pricing intelligence into their app.
Where does the API key come into this?
As a developer or business owner, the API key is your way of ensuring that access to your creation remains in check. The API key distinguishes the authorised users and their actions, making it possible for you to keep a watchful eye on the usage. With that key, you can maintain, manage, and even derive value from your APIs.
We’ve now discussed most of what you need to about APIs, so let’s explore the different types of web API that are available and how they work.
REST APIs: REST stands for ‘Representational State Transfer’ and is used to describe APIs that follow a specific architectural style and set of constraints for creating web services. Rest APIs use standard HTTP methods and are known for their simplicity and scalability. We used this structure in our example above.
SOAP APIs: Our next API type is SOAP which stands for ‘Simple Object Access Protocol’.
SOAP APIs are a protocol for exchanging structured information in the implementation of web services and use XML (our extensible markup language) for message formatting. Soap is relatively outdated, and when compared with REST, can be somewhat difficult for humans to read and understand.
GraphQL APIs: GraphQL is a query language for APIs that allows clients to request exactly the data they need and nothing more. Unlike SOAP and REST, which provide fixed responses, GraphQL allows the client to define its data needs, reducing over-fetching and under-fetching of information. This flexibility in data retrieval makes GraphQL particularly useful in scenarios where fine-grained control and optimised resource usage are essential.
GraphQL is a protocol (an agreement of information exchange) that can be used over HTTP (like REST) or over a WebSocket or standard socket.
WebSocket APIs: Lastly, we have WebSocket APIs. As mentioned above, these can be used with GraphQL as well as RESTful APs. WebSockets are used for real-time applications where low latency and two-way communication are essential. They're vital for instant interactions, making them a go-to choice for chat apps, online gaming, and financial data feeds. Some common examples include Facebook Messenger and Slack, as well as real-time features on Google Docs and Figma. Websockets are now widely supported in modern browsers.
Remember, these are just a few examples of API types, and there are many more specialised APIs designed for specific purposes and industries, such as payment gateways, weather data APIs, and geolocation APIs.
The choice of API is always dependent on the specific requirements of the project or application.
So, how do these API types work in conjunction with one another? It’s time for some more examples…
A holiday home comparison website
Picture a holiday home comparison website akin to Airbnb. This platform relies on a combination of APIs to ensure user satisfaction. Here’s what we have happening behind the scenes:
Let’s take a look at another example.
How about a smart weather app?
Imagine we’ve created a shiny, new weather app that delivers real-time weather insights with a personalised touch. Here’s what we’ll include:
In these scenarios, a dynamic interplay of APIs is at work, each serving a distinct purpose.
By bringing them together, they help to create applications that meet user expectations by seamlessly accessing external services and data sources.
When we use any type of software component or web application, we need to make sure that it’s secure.
The security of APIs can vary widely depending on how they are designed, implemented, and managed. While many APIs are secure and undergo rigorous testing and security measures, vulnerabilities can exist if proper precautions are not taken.
So, what constitutes a safe API?
First, your API needs to prioritise authentication and authorisation.
One way to authorise users or applications is with an API key, as we mentioned above, however, this alone definitely isn’t enough to protect your API.
Companies such as Apple and Google, use a protocol called OAuth 2.0 which is an example of token-based authentication. In OAuth 2.0, the "token" acts as a credential that provides access to a resource or service without revealing the user's actual login credentials (such as a password). The idea is that it allows third-party apps or services to access a user's data securely, without exposing sensitive information.
Other common authentication methods include multi-factor authentication which relies on multiple forms of verification, and role-based access control, where specific roles and permissions are granted to users or applications to restrict access to certain API endpoints or functions.
Next, you need an API with data encryption.
Implementing data encryption using HTTPS (SSL/TLS), allows you to protect data during transit.
What this means is that, when information is sent between a user's device and a website or service, it becomes scrambled and secure. This encryption ensures that even if someone intercepts the data as it travels over the internet, they won't be able to decipher it.
For example, when you enter your credit card details on an e-commerce website for an online purchase, the website uses HTTPS to encrypt your data during the transaction. This encryption makes it extremely difficult for unauthorised parties to intercept and decode your sensitive information while it's in transit over the internet. Nowadays, HTTPS is a standard security measure for all online businesses, not just major online retailers. So, if you don’t see the padlock, think twice before you go sharing any of your precious details!
Another critical security measure is rate limiting.
Rate limiting shields your API from abuse and potential threats like Distributed Denial of Service (DDoS) attacks. For example, the API used by X, (formerly known as Twitter), deploys rate limiting to control the volume of requests that an application can make within specific timeframes, effectively curbing excessive usage.
This means that even if a popular app or service interacts with X's API, the rate limit prevents it from overwhelming the system with too many requests in a short period. In turn, this ensures a fair and secure experience for all users and helps maintain the stability and availability of the API and the platform it serves.
Lastly, practices such as monitoring, logging, regular updates, and patching are crucial for real-time threat detection because they allow you to swiftly identify and respond to security issues and vulnerabilities as they happen.
Microsoft Azure APIs, for instance, capture data on the volume and patterns of incoming requests, the geographical locations of users, and the types of operations performed. This information enables Microsoft’s API administrators to gain a deep understanding of how the API is utilised and identify any irregularities or unusual patterns.
When users log in, their APIs also record comprehensive data about API interactions, including request details, response data, and error messages. By carefully analysing these logs, it becomes possible to detect suspicious activities. For instance, a sudden increase in failed login attempts or repeated requests for sensitive data can trigger alerts.
We’d be lying if we said that APIs are the only way for software systems to communicate and share data. Yes, APIs are the preferred choice, however, there are some alternatives that you should know about. Let’s whizz through a few…
Webhooks
Webhooks (also known as reverse APIs) offer a way for one application to send real-time data to another when a specific event occurs. Instead of actively polling an API for data, the receiving application is notified when there's new information available. In short, webhooks provide updates without being summoned. Whereas, APIs require a request.
Pros: Webhooks often require less effort for initial setup and consume fewer system resources compared to APIs.
Cons: Since they are designed specifically for receiving data, they don’t support actions like pushing, modifying, or removing data in another system. This means that they aren’t well-suited to intricate integrations that demand bidirectional communication or data removal capabilities.
Message Queues
Message queues facilitate asynchronous communication by managing the efficient delivery of messages, making them particularly useful in scenarios where systems need to handle varying workloads and when multiple endpoints need to consume the same message without the sender needing to know each recipient individually.
Pros: Message queues allow systems to process tasks and messages at their own pace without requiring real-time interactions, which is especially useful for managing high workloads and maintaining system reliability.
Cons: Because they don’t provide synchronous communication, they can be unsuitable for situations where instant, real-time interaction between applications is essential.
FTP
In rare cases, data exchange can be achieved through file transfer mechanisms such as FTP. This involves sending data files (e.g., CSV, XML, JSON) between systems. While not as real-time as APIs, file transfers can be a simple way to share data.
Pros: FTP may be helpful for bulk transfers and can be well-suited to older, legacy devices that lack support for encryption of any kind.
Cons: FTP often causes time delays due to its multi-step process and limited ability to handle multiple tasks simultaneously. It is also quite outdated and not often used for formal communication between systems.
Why would you choose an alternative?
Well, you don’t always have to. Features like Webhooks and Message Queues can be used in conjunction with APIs however it totally depends on your requirements.
Your business needs to factor in data volume, real-time requirements, security, and the capabilities of the systems involved.
There’s no doubt that APIs remain a popular choice for many scenarios due to their flexibility, standardisation, and ease of use. However, for specific use cases or to solve particular problems, sometimes the alternatives above may be a better fit.
According to research conducted by Vanson Bourne in 2021, over half of large corporations report having over 100 APIs and, in a 2023 survey conducted by Postman, it was found that 53% of businesses were planning to increase investments in API for 2024.
As we can see, the API ecosystem is growing expeditiously. Businesses are not only acknowledging the benefits of APIs, but also placing their trust in them and developing a reliance on them.
What do we think?
We’re excited about the future of APIs and always eager to discover how they’ll help us to power new innovations. However, and we’ve said this before, our primary aim is always to help you make the most informed decision for your business.
Our interests don’t lie in promoting one approach over another. We don’t have any hidden agendas or a financial motive pushing us to favour a single product or service. So, if we think you’re better off with an alternative, we’ll always let you know!
Beyond the technical details of HTTPS or WebSockets, the fundamental simplicity of data exchange does not change. One system passes a key and a request in a particular way and another system somewhere responds.
This data exchange and information flow is something our designers and developers obsess over and the core is often simple for everyone to understand. Knowing these layers allows you to be effective at all levels of technology design and development.
In the book “Exponential Organizations”, the authors make a point that all businesses should consider how their business could be served as an API. It’s a good way to reach more customers and enable other services to integrate with yours.
How can you turn what your company does into a platform?
Making this discoverable on the internet and in public could not be more important with the advent of digital assistants and agents. Indeed, the vast majority of future business might be conducted through our AI assistants and agents - just like how companies now are found (and made or broken) by their websites being discovered and indexable by Google.
If you want to hear more on this, check out my “Future of IoT” talk from Bristol Tech Festival where I share my thoughts on a programmable world powered by APIs!
Intrigued by APIs?
Let’s sit down together, get to know each other and figure out the best digital solutions for your business.
Reach out to us on 0117 205 0425 or drop us a line here: hello@newicon.net
Subscribe to get our best content. No spam, ever. Unsubscribe at any time.
Send us a message for more information about how we can help you