[Part 1] Guide to APIs: HTTP & 3 API protocols you need to know

Ever heard of RESTful APIs or GraphQL?

If you’ve worked in the tech industry for a while, it’s likely you have. But before we jump into what they are, let’s briefly touch on APIs.

APIs are the ultimate communicators of the internet and they allow two applications to communicate with each other.

APIs are all around us. Every time you use a rideshare app, pay off a credit card balance, or send a DM on your social media platform of choice, etc. To get an idea of how ubiquitous APIs have become, check out this cool graphic on API usage in 2020:

APIs do not generally impact user experience (although they can if performance hinders them). Instead, APIs impact developer experience — how easy it is to connect and integrate with another system.

Anything that impacts developer experience potentially impacts the product roadmap, so the more you know about them the more prepared you’ll be during technical discussions.

API Protocols

Not all APIs are built the same way — they’re built around what are called communication protocols and there are a few of them.

API protocols are like the universal translators of the digital world. They are a set of rules and conventions that let different software applications talk to each other in order to share data and functionality. Imagine you have two friends who speak different languages, and you want to help them communicate. API protocols are akin to the translator who bridges the gap between them.

These protocols dictate how information should be structured and exchanged, so that when one app sends a message or API request, the other app understands it perfectly.

Think of it as a standardized menu in a restaurant; you know what to expect when you order a “hamburger” or “spaghetti” and the waiter knows exactly what you’re asking for. The menu is what helps you and the waiter communicate.

There are various types of API protocols but the most widely-used are the following 3: REST, SOAP, and GraphQL.

Quick note: APIs can support communication with APIs of different protocols (though engineers need to write code to support multiple protocols). Email Servers, for instance, supports requests from APIs using the REST and SOAP protocol. The Google Maps API also provides a comprehensive web service that supports multiple types of interaction and connectivity.

REST: Representational State Transfer

REST APIs are everywhere in modern web and mobile applications, which means most of the APIs you’ll come in contact with, and likely your engineers are building will be REST APIs a.k.a. RESTful APIs.

REST APIs have become the de facto standard for building web services and enabling efficient communication between software systems due to their simplicity and scalability.

REST APIs uses JSON for its data format and the HTTP/HTTPS methods to interact with resources and transmit data from one application to another. REST APIs are more flexible than SOAP APIs (see next section on SOAP), but are also limited in its transmission types.

Here are the components of a REST API call:

• HTTP method (POST, GET, PUT, DELETE): the action that the API is taking (i.e. retrieving data, updating data, creating new data, etc..)
• Endpoint (URL): the location the data is being sent to and where the API is accessed.
• Header: data about the data (such as the origination server).
• Body: the information actually held within the transmission.
  
  

For instance, when you submit a contact form on a website, your browser is making a REST API request to a server with the data you submitted. Anytime you create a new post on a social media platform (i.e. Twitter, Facebook, Instagram), a REST API is made to a remote server to store the data in the database and once successful, your feed will update.

GraphQL

GraphQL is the newest type of API protocol to enter the field as it’s become popular within the last 10 years. GraphQL was developed by Facebook in 2012 but later open-sourced in 2015, gaining popularity for its flexibility and efficiency.  They’re a modern approach to requesting and delivering data between software applications.

Unlike REST APIs, where clients receive a fixed set of data from predefined endpoints, GraphQL APIs allow clients to request precisely the data they need and nothing more. This precision is more performance as less data is being transferred across the wire.

A GraphQL API consists of three main components:

• Query: This is the client’s request for specific data. Clients can specify the exact fields they want, which helps reduce over-fetching of data.
• Schema: The schema defines the structure of the data available through the API, including the types of data and the relationships between them. It serves as a contract between the client and server.
• Resolver: Resolvers are responsible for fetching the requested data. They determine how to retrieve and format the data based on the client’s query.

Compared to REST and SOAP APIs, GraphQL APIs offer more control to clients and reduce the problem of over-fetching or under-fetching data. They have gained popularity, especially in modern web and mobile app development, where fine-grained control over data retrieval is crucial for performance and user experience.

GraphQL APIs are typically used in scenarios where customization and efficiency are important, such as social media platforms, e-commerce websites, and applications with complex data requirements. They enable developers to build more responsive and optimized applications by allowing clients to request only the data they need, resulting in faster load times and improved user experiences.

As a result, GraphQL has become a popular choice for many developers seeking a more flexible and efficient way to interact with APIs.

SOAP: Simple Object Access Protocol

Before REST APIs, SOAP APIs were the communication protocol of choice having been around since the late 1990s. They were once super popular, particularly with enterprise-level applications where secure and structured data exchange was critical.

But SOAP APIs have seen a decline in recent years, as simpler and more lightweight alternatives like REST APIs gained traction. REST’s simplicity made it more attractive for web and mobile app development. However, SOAP is still relevant, especially in scenarios where data integrity and security are paramount, such as financial transactions and healthcare systems. It’s also commonly used in enterprise applications that require standardized communication.

SOAP uses XML as its format for data exchange. It consists of several key components:

• Envelope: This is like the outermost wrapper, which defines the start and end of the message.
• Header: This is optional and contains metadata about the message, such as authentication or routing details.
• Body: The heart of the message, where the actual data resides.
• Fault: Also optional, it contains information about any errors that may have occurred during the message exchange.
  

TL;DR: In Summary

There are a number of communication protocols out there but SOAP, REST and GraphQL are the most widely used. It’s not important to memorize the technical details of each. It’s more important to have a broad landscape understanding of the types of APIs so you know what’s being discussed and can do an appropriate search engine query (or refer back to this essay) if additional detail is required.

Here’s a quick graphic comparison of the 3 API protocols:

In summary, SOAP APIs have a history of being widely used for their structured and secure communication, although they have become less popular compared to REST APIs, which are simpler and more adaptable for modern application development. SOAP APIs are still prevalent in specific domains where data integrity and reliability are crucial.

 

Sign up for the Skiplevel newsletter to get more content like this straight to your inbox.

If you like what you read, make sure to ❤ it, share it, and leave any thoughts in the comments!

Follow and subscribe for more technical tips!

Want to feel more confident in your technical skills?

Become more technical in just 5 weeks, without learning to code! We also train teams! Find out more at skiplevel.co/teams and book a call with me to get started.

Skiplevel is a program that helps product managers and teams become more technical without learning how to code.

Learn more about the Skiplevel program ⟶

Connect with Irene on LinkedIn and Twitter and follow Skiplevel on LinkedIn, Twitter, and Instagram.