What is API exactly? Things I wish I had known earlier.

angelleeangellee
7 min read

Table of contents

Have you ever wondered what an API really is? Why do people often mention APIs in software development, especially for backend engineers?

API stands for application programming interface. The next question is, what does "Application" mean in API, and what does "Interface" mean in API?

"Application" in API refers to any software with a specific purpose or functionality, while "Interface" refers to something that allows interaction with the system or whatever is behind the interface.

If we put it together, an API is a contract or protocol that dictates the communication between 2 different applications. Developers know that they can rely on API because the API makes the connection between the API providers and the consumer (API user) much more efficient since the interfaces are documented, consistent, and predictable.

Examples of APIs

You can find API anywhere in the codebase, basically when you are:

1. Calling a function or method from a software library or interacting with external web services, that's an API.

Whenever you're using a function or method from an external library (like requests in Python or axios in JavaScript), you're interacting with an API. This allows you to perform operations without knowing the internal implementation details of that library

Example:

const axios = require('axios');

axios.get('https://api.example.com/data')
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('Error fetching data:', error);
  });

2. Using database drivers or ORM methods.

When you use libraries like pg for PostgreSQL or ORMs like Hibernate to query a database, you’re actually working with APIs. These APIs simplify things by wrapping complex SQL commands into easy-to-use functions or methods—so you don’t have to write raw SQL queries yourself every time.

Example (Kotlin using Exposed ORM):

// Getting users data where their ages is above 18, and only show the username in list format
val users = Users.select { Users.age greaterEq 18 }.map { it[Users.name] }

3. Communicating between Microservices.

When different services in a microservices architecture need to talk to each other, they often use APIs like REST or gRPC to send data back and forth. This communication through APIs keeps everything connected and working smoothly.

Example (Kotlin with Spring Boot):

@GetMapping("/api/v1/users")
fun getUsers(): List<User> {
    return userService.getAllUsers()
}

4. Accessing system resources or OS Capabilities.

APIs also let you tap into system-level functions, such as reading and writing files or handling network communication, which are made available by the operating system or runtime environment—like the Java Standard API or Python’s os module.

Why do we need an API?

Ok, now you understand what exactly is API. So, you might start wondering why we need API in the first place. Here are the key reasons why APIs are so important:

1. Abstraction of Complexity.

APIs let us use powerful features without needing to understand all the technical details behind them. Take Stripe, for example: you don’t have to know how payment processing works under the hood—you can just call the Stripe API and handle payments effortlessly.

2. Interoperability between systems.

APIs act as universal translators, enabling different systems—often built with different languages and technologies—to communicate and work together smoothly

3. Reusability of code.

With APIs, developers create a reliable set of tools that can be reused again and again across projects and platforms, saving time and effort.

4. Security and controlled access.

APIs help providers control who can access their systems and what actions they can perform, which is essential for maintaining security.

5. Scalability.

APIs allow each service or component to be scaled independently. So, if one part of an application gets high traffic, you can scale that part without affecting everything else.

API Types

APIs come in different flavors based on who can access them and how they function:

  • Public APIs: Open to anyone, often with minimal restrictions.

  • Private APIs: Used internally within an organization, not exposed to external users.

  • Partner APIs: Shared with select business partners to enable specific integrations.

API Protocols

API protocols are the rules that define how data is formatted, sent, received, secured, and processed between systems.

A. Common API Network Protocols

  • HTTP/HTTPS: The foundation for most web APIs, including REST and GraphQL.

  • gRPC: A fast, modern protocol by Google based on HTTP/2.

  • WebSockets: Enables real-time, two-way communication over a single connection.

B. Library Protocols

Library protocols differ by working within the same system or application, exposing public methods and interfaces that other parts of the system can call directly through compiled code—no network required.

API Data Format.

A. Text-Based Formats

These are human-readable and easy to debug:

  • JSON: Lightweight and popular for web APIs.

  • XML: Verbose but still used, especially with SOAP APIs.

  • YAML: Highly readable and used in configuration and DevOps.

  • CSV: Simple tabular data often used for bulk import/export.

B. Binary Formats

Compact and fast, suitable for performance-critical uses:

  • Protocol Buffers (Protobuf): Google’s schema-based binary format used with gRPC.

  • Avro: Flexible format popular in big data ecosystems.

  • MessagePack: Efficient binary version of JSON for mobile and IoT.

Architectural Styles

  • REST uses HTTP methods and is the most popular style for web APIs.

  • GraphQL allows clients to ask for exactly the data they need from one endpoint.

  • SOAP is an older XML-based protocol known for security and reliability.

  • Webhooks are event-driven HTTP callbacks that notify apps instantly when events happen without repeated polling.

  • RPC: Some people might think gRPC is an architectural style, nope, gRPC is a protocol that implements the RPC architectural style. Then. The next question is “what is the RPC architectural style? and how it differs from gRPC?”

RPC (Remote Procedure Call) is a way of designing systems where a client can call functions or methods on a remote server just like they would call local ones. Instead of focusing on resources, RPC is all about performing specific actions or procedures remotely. This lets you directly execute code on another machine across a network. RPC can keep track of state or be stateless, and usually involves sending parameters to the remote function and waiting for its response.

gRPC, created by Google, is a modern and efficient protocol that brings RPC into the present day. It uses HTTP/2 for faster and more reliable communication and relies on Protocol Buffers to pack data tightly and speed up processing. Beyond classic RPC, gRPC adds cool features like two-way streaming and support for many programming languages, making it an excellent choice for building microservices and distributed systems.

In short, RPC is the general idea of calling remote functions, while gRPC is a powerful, up-to-date way to make those remote calls happen effectively.

Footnote and Key Terms:

Protocol: a system of rules that explain the correct conduct and procedures to be followed in formal situations.

Contract: an agreement between parties.

Library: a collection of pre-written code that you can use to perform specific tasks, source The difference between libraries and frameworks

Third party: software or application created by programmers or publishers independent of the manufacturer of the hardware for which it is intended. source dictionary.com

Abstraction: In the computer science context, abstraction is the concept of hiding the complex implementation details of a system or process and exposing only the necessary, high-level functionality to the user.

Interoperability: in the context of APIs, refers to the ability of different systems, software applications, or services to communicate and work together seamlessly.

References:

0
Subscribe to my newsletter

Read articles from angellee directly inside your inbox. Subscribe to the newsletter, and don't miss out.

API ProtocolAPIsSoftware Engineeringbackend developmentsComputer ScienceRESThttpgRPCGraphQLTechExplained#TechExplainedSimply

Written by

angellee
angellee