APIs: All You Need To Know

APIs: All You Need To Know

An all-you-need-to-know primer on APIs.

·

7 min read

Why on earth are there so many acronyms in tech?

Acronyms are a double-edged sword. They're an accordion for simple ideas. They compress complex concepts or phrases into individual letters so that they can be easily recalled later on.

As an ex-copywriter, my brain was conditioned to steer clear of bad habits, including acronymizing words. So in tandem with having to quickly absorb myriad new web development concepts -- I found myself suffering from a hapless case of acronyphobia. Alas, I concluded that learning how to code would be much harder if I made acronyms the enemy.

Meet my very first acronym friend: API (Application Processing Interface).

In this article, I present a comprehensive primer on APIs. By the end, you should be able to answer these 5 questions:

  1. What is an API?

  2. What are the differences between Remote and Web APIs?

  3. What are the three most common APIs?

  4. What is an API endpoint?

  5. What are the strengths and weaknesses of APIs?

What is an API?

It's a remote! It's a messenger! -- No, it's an API.

Let's explore the concept of an API (Application Processing Interface) with a non-technical example:

Think of the last time you were so unwell you had to pay a visit to your local doctor. He decided you needed more than just hydration and rest. He prints a detailed form with instructions for certain prescription medicine and sent you on your way to the nearest pharmacy. You are the 'client'. Once you arrive at the pharmacy, you hand over your prescription to the pharmacist, who gives you a confident nod and then quickly disappears into the back. About 5-10min later depending on the complexity of your request -- the pharmacist reappears with a personalized package with the prescribed medication.

The most painful part of this process was the wait. You didn't need to sift through the dispensary yourself, meticulously weighing the dosage. The pharmacist decoded your prescription and then delivered it to you -- all ready to go.

APIs are the pharmacists of software development. They receive information from a client (you) and take care of all the tricky stuff behind-the-scenes so that you can easily access the functionalities (your medication) of the pharmacy (the software).

Alright, so let's move on to a technical example. As a remote worker, my main form of communication with my team is through Slack — a leading messaging tool. Although digital, I feel I can express my emotions better than IRL with Slack, with its snazzy GIPHY integration. Life would be very dull without the ability to respond via GIFs. But Slack ain't a GIF company. It is not in their interest to have the most extensive library of GIFs, but it is in their best interest to ensure that teams have the best remote communication experience. By integrating GIPHY's API, they grant users access to the entire directory of GIFs on GIPHY. Win-win.

technical example diagram of APIs with slack and GIPHY


A Brief History of APIs

By now, it should be clear that APIs are extremely powerful. They augment the web easier and make it more enjoyable for both developers and users

This might surprise you, but APIs were born before the personal computer. Their rise to relevance began with being local libraries for operating systems. It took almost 30 years for APIs to be freed from their local environments and it wasn't until the early 2000s that they became integral for remote data integration. Remote APIs were created to be the conduit for communication networks -- i.e. the Internet. They were 'remote' as the data being manipulated was held outside of the local computer making the request.

For this, most modern-day APIs are designed according to web standards.

Not all remote APIs are web APIs; but all web APIs are remote APIs

the relationship between remote and web APIs

Check-in time:

  1. What is an API? ✔️

  2. What are the differences between Remote and Web APIs? ✔️

  3. What are the four most common APIs? ⭐ We are here!

  4. What is an API endpoint?

  5. What are the strengths and weaknesses of APIs?


Common Types of Web-based APIs

We see multiple types of interfaces in our daily lives. To name a few -- your TV remote, your apartment intercom, and even your restaurant waiter. APIs are just as varied. As web developers, we get to choose which one to implement depending on the purpose and features.

REST APIs

REST is short for Representational State Transfer. REST APIs are commonly referred to as 'RESTful APIs'. Why? Because they're chill. And by chill, I mean that they are the top choice for seamless client-server. They're easy, simple and scalable.

Traits:

  • Based on Uniform Resource Identifiers (URIs)

  • Based on the HTTP Protocol:

    • Uses JSON for data formatting (making it super browser compatible)

    • Can receive various data formats (XML, JSON, YAML, and more)

  • Not tied to any particular resources or methods — which makes it simple to build and scale.

  • Stateless — think API amnesia! It retains nothing from the exchange which means no content is stored between requests. Your users can chill out about their data being stored without their permission 😎.

SOAP APIs

SOAP stands for Simple Object Access Protocol...but in reality, it's not so simple. I won't get into the particulars, but just remember that REST APIs are much more beginner-friendly.

Traits:

  • Can only handle XML data formats

  • Uses a common communication protocol (whereas REST is driven by architecture)

  • Higher levels of security and accuracy than REST.

GraphQL APIs

GraphQL is a query language and server-side runtime. It is often considered the alternative to the shortcomings of REST APIs. They are also one of the most advanced in terms of technological understanding. GraphQL APIs prioritize efficiency in that it returns exactly what the client requests -- nothing more.

Traits:

  • Client-driven (REST is server-driven).

  • Organized by schema and strict typecasting (REST has endpoints)

  • A single call with specific data (REST calls multiple calls with fixed data)

There are two more web-based APIs I did not cover: XML-RPC and WebSocket APIs, mainly because REST, SOAP and GraphQL APIs are the three most common ones I have seen reading on APIs in my career to date.

API comparison chart - REST, SOAP, RPC, GraphQL

What is an API Endpoint?

Recall that an API is a middleman or messenger between two (software) programs. An API endpoint is the entry point for the transfer of data. This might be where the API call is received, and the exchange is triggered.

Endpoints are important because they provide the API call a direction.

In the case of no valid endpoint:

  • The API will be hella confused.

  • The response will not be generated promptly

  • Higher likelihood of incorrect response

API endpoint diagram with Pinata and IPFS

The relationship between API requests and endpoints is shown in the diagram above. The client will send an API request via a URL to the Pinata API service, which then renders that request to retrieve data from that particular endpoint from the server/database, IPFS.

Strengths and Weaknesses of APIs

APIs are ubiquitous on the internet. Some say the future of software and web development is API-centric. Although each type of API has its strengths and weaknesses, here are some overarching ones to note.

Strengths:

  • Accessibility — Enables easy data access and sharing by enabling bridges between systems.

  • Modularity — Developers can access and leverage the functionalities of other applications seamlessly. This reduces time-to-market for complex digital products.

Weaknesses:

  • Security — As a single gateway to information, hackers have a field day trying to infiltrate APIs.

Before you go ahead and "shoot the messenger", APIs are equipped with a respective protective layer, as well as a variety of testing mechanisms to prevent such infiltrations.

Here are some resources to read more about API security best practices and the importance of API testing.


And with that, you should now have a solid understanding of what APIs are, how they work, what the different forms are, as well as how they power (and sometimes jeopardize) the world of software development.

Thank you for hanging on till the very end. You are a champ 👊.

If you found this useful or at least found my writing amusing -- please emoji react, give it a heart, and share it with your friends who might be on a similar journey.

If you have any feedback or suggestions, feel free to drop 'em in the comments, or HMU on any of my social channels: Twitter, IG, or email.