While no two APIs are exactly the same, they do tend to share a lot of characteristics, from design features to data formats. Looking closely at these traits allows us to identify distinct types of APIs, which we can use to set clear expectations, discuss what does (and doesn’t) work, and stick to relevant best practices.

The only problem is: there’s no one way of categorizing APIs. So in this article, we’ll look at four basic API taxonomies based on both technical and business-related characteristics: provisioning, design style, protocol, and data format. Without further ado, here are the many types of API that should come in handy if you’re planning, building, or managing an API.

API Types by Provisioning: Private, Partner, Public

One way to categorize APIs is based on their provisioning (in other words, in who gets to use them). Public APIs are the APIs we come across every day, and they are designed to be used by — you guessed it — the general developer public. These APIs can be both free and paid; what’s important is that anyone can sign-up for access.

Next up are partner APIs, which are designed to be used by a select group of pre-registered developers. They are commonly employed in platform marketplaces, where the API keys necessary for development are only shared with registered partners.

Finally, there are private APIs, which are designed for internal use (within an organization) only. For example, a bank might have a private API that can read an account’s balance and transaction history. An API like this can greatly simplify the development of front-end interfaces, but definitely shouldn’t be shared with the public!

API Types by Design Style

Perhaps the most insightful way to categorize APIs is by their architectural style. In this sense, the most popular type of API is REST. REST, which stands for representational state transfer, is a simple, resource-based approach to building APIs. Consumers send GET requests to access a resource, and PUT, POST, and DELETE requests to modify it.

An alternative design style that is quickly growing in popularity is GraphQL. Unlike REST, which relies on discrete, predefined resources, GraphQL allows the consumer to choose the information they want to receive (based on whatever parameters they have) by specifying that information in the request. This fixes two big limitations of REST: under-fetching, where not enough data is returned, and over-fetching, where too much data is returned.

Falcor is an architectural style that is often compared to GraphQL since it also seeks to address the shortcomings of REST. The basic premise of Falcor is that all of your data is represented in a single JSON object (more on that later). Falcor also includes referencing functionality, which turns the JSON data tree into a data map.

RPC is another design style that is worth mentioning since it is often confused with REST. The big distinction is that RPC is action-based, whereas REST is resource-based. Take the hypothetical example of an endpoint used for registering user accounts: REST would accomplish this with an /accounts resource, while RPC would use a /signup endpoint.

It is worth mentioning that SOAP — which is actually a communication protocol — is often associated with its own design style. SOAP APIs usually use RPC as a design style, which is why they’re often juxtaposed (architecturally) with REST.

API Types by Protocol

Another way to categorize APIs is based on the protocol they use. This is a much more complicated distinction since protocols operate on different levels and aren’t always mutually exclusive. The best-known and most often used communication protocol is HTTP, which is a simple and effective way of sending and receiving messages. HTTP and its more secure counterpart HTTPS are the protocols used by the vast majority of APIs.

HTTP is a fantastic protocol under good conditions but can leave something to be desired otherwise. MQTT, AMQP, and CoAP are all popular protocols designed to address HTTP’s shortcomings. MQTT is built to be lightweight, especially in terms of bandwidth usage. Also, this protocol is asynchronous, which means clients don’t have to wait for a response from a slow server. AMQP offers the same benefits, but with a better fleshed-out functionality set. Finally, CoAP is also designed to operate under speed and size constraints (that’s the c in CoAP) and meshes well with HTTP.

Another protocol you should be aware of is SOAP, which finds itself in a slightly different category to the communication protocols above. SOAP defines how data should be sent using a markup language called XML. It often operates over HTTP, but can also use other protocols like AMQP. Unfortunately, SOAP has come to be associated with a clunky, old-school approach to designing APIs.

API Types by Data Format

We mentioned XML above, which is an example of a data format that APIs often use. The main benefit of data formats like XML is that they are both human- and machine-readable. XML itself has a wide range of features but is criticized for its heaviness.

Here’s an example of a simple XML entry:

  Thomas Bush
  
  2019
  
    provisioning
    design styles
    protocols
    data format
  

JSON is a slightly cleaner, but more limited alternative to XML. It is quicker to read and write under most circumstances and uses a simple key-value pair structure. An even easier alternative to JSON is YAML, which is still powerful enough for most use cases.

Here’s that same example formatted in JSON:

{
  "article": {
    "author": "Thomas Bush",
    "title": "API Taxonomies Explained",
    "year": 2019,
    "topics": [
      "provisioning",
      "design styles",
      "protocols",
      "data formats"
    ]
  }

…and here it is in YAML:

article:
    author: Thomas Bush
    title: API Taxonomies Explained
    year: 2019
    topics:
        - provisioning
        - design styles
        - protocols
        - data formats

While these are some of the most common data formats in API design, there are plenty more out there.

Conclusion

Clicking onto this article, you may have hoped there are just a few “types” of API to get familiar with. Now that you know there are so many ways to categorize APIs, you can see why this isn’t all too easy. With that said, it is easy to classify APIs by their provisioning rules or data formats; unfortunately, it is a little more complicated to do so by protocol or architectural style, but it is still very possible!