Types of APIs - A Complete Overview

Discover the different types of APIs including REST, SOAP, GraphQL, WebSockets, JSON-RPC, XML-RPC, and gRPC. Learn how each API type works, their key features, and when to use them in your projects.

Table of Contents

Now that you know what we document and how we document, it’s time to explore the diverse world of APIs, and I’ll explain them in a way that’s easy to grasp.

We’ve six broad categories of APIs:

  1. Web service APIs: These are like the superheroes of the internet. They help all sorts of websites and apps talk to each other. Some cool ones are REST, SOAP, GraphQL, and more.

  2. Library-based APIs: Think of these as ready-made toolboxes for programmers. They come with handy tools (functions or classes) for doing specific jobs, like building stuff in a video game.

  3. Class-based APIs (Object-Oriented): These are like special toolboxes that organize their tools in a very neat and organized way, just like how your toys might be sorted into different boxes.

  4. Functions or routines in an OS: The operating system (the boss of your computer) shares some secret codes with programmers. These codes help programs use the computer’s special powers.

  5. Object remoting APIs: Imagine if you could send messages to your friends using magic spells. Object remoting APIs are like those spells, making objects in different places talk to each other.

  6. Hardware APIs: These are the keys to unlock the superpowers of your computer’s hardware, like the graphics card or the sound system.

In this tutorial, we are more interested in understanding Web service APIs. Why? Because 80-90% of the time, you are going to document Web service APIs only.

Different types of Web APIs including REST, SOAP, GraphQL, and WebSockets

The Web service API encompasses:

  • REST API
  • SOAP API
  • GraphQL
  • WebSockets
  • JSON-RPC
  • XML-RPC

  • gRPC

REST API (Representational State Transfer)

So, first up, we have the REST API. Imagine it as the simplest way to design apps that talk to each other over the internet. It’s like going to a restaurant with a menu. You pick what you want (using simple commands like GET, POST, PUT, or DELETE), and the kitchen (the server) gets it ready and serves it to you. REST is known for being straightforward, scalable, and it works with pretty much anything on the web.

SOAP API (Simple Object Access Protocol)

Next, we’ve got the SOAP API. This one is a bit like sending letters, but with strict rules. Everything has to be in a specific order and format, just like how you need to write an address on an envelope in a particular way. SOAP is all about strong security and reliability, making sure your message gets to the right place.

GraphQL

Now, let’s talk about GraphQL. It’s like ordering a customised pizza. You get to choose exactly what toppings you want, and you won’t get anything else. With GraphQL, you request just the data you need in a single go. It’s super flexible and efficient, especially when you don’t want to waste time or data.

WebSocket

Moving on to WebSockets. These are like having a phone call where you can talk and listen at the same time. It’s different from traditional mail (like sending letters) or email (where you send a message and wait for a response). WebSockets are great for real-time stuff like chatting and live updates.

JSON-RPC and XML-RPC

Now, let’s talk about JSON-RPC and XML-RPC. These are like asking a friend to do something specific for you, and your friend knows exactly what you want. It’s a way for one program to request a particular action from another program. These types are handy because they can work with different programming languages, making them a good choice for big, distributed systems.

gRPC

Last but not least, gRPC. Think of gRPC like sending a super efficient and structured letter with a built-in translator. It makes sure both the sender and the receiver understand each other perfectly. gRPC is known for high performance and strong typing, which means it’s fast and reliable.

Intrigued by the fascinating world of APIs? Well, guess what? There’s more to explore in the next chapter, where we dive deeper into the superstar of APIs - REST APIs. Get ready for an exciting journey into its intricacies and applications. Stay tuned, and let’s unravel the secrets together!

API Selection Tip
When choosing an API type for your project, consider factors like data complexity (GraphQL for complex data needs), real-time requirements (WebSockets for live updates), enterprise needs (SOAP for strict security), or simplicity (REST for most web applications).

Key Takeaways

  • There are six broad categories of APIs, with web service APIs being the most commonly documented
  • Web service APIs include REST, SOAP, GraphQL, WebSockets, JSON-RPC, XML-RPC, and gRPC
  • REST APIs use simple HTTP methods and are known for being straightforward and scalable
  • SOAP APIs follow strict protocols for reliable message exchange
  • GraphQL allows clients to request exactly the data they need in a single query
  • WebSockets enable real-time, bidirectional communication
  • As a technical writer, you'll primarily focus on documenting web service APIs (80-90% of API documentation)
Previous: How do Technical Writers document? Next: More on REST APIs
Start your learning journey!
Course Progress 0%
0 of 0 pages completed

Found value in the course?

Your support fuels my work!

Buy Me A Coffee