Types of API

APIs (**Application Programming Interface**), like any other concept in software development, have different types. Developers build API for various purposes using different technologies and programming languages and follow different architectural styles, which result in entirely different kinds of APIs. To learn more about APIs, we highly recommend the [What is API](/blog/what-is-api/) article.

This post will explore the world of APIs from two different perspectives: User & Architecture. It gives you a good understanding of the different types of APIs, their use cases, and how you can leverage them. Whether you’re planning to develop an API or curious to know about APIs in general, this post has something for you, so without further ado, let’s get started.

## API types by user Software teams build APIs for developers and other software teams to use. The general public, partners and programmers within organisations are some of the common groups of API users. Depending on the target audience of API, we can break APIs down into three major categories:
### Open API **Open API** (sometimes called **Public API**) is a publicly available free API for anyone to use. Some Open APIs are rate-limited, which means you can send a limited number of requests to the API during a period. Rate-limiting public APIs help with fair usage of the API by all customers. Some Open APIs require API Key to authorise access to the API. Read the [What is API Key](/blog/what-is-api-key/) to learn more about API Keys and how to get one.

Some of the widespread use cases of Open APIs are:

• Governments make public data available through Open APIs. For example, the US government offers API for various datasets via the data.gov project. Transparency, research & development, and innovation are just some reasons why governments invest in Open APIs.
• Data-centric non-profit organisations make their valuable data available through APIs for the general public to use.

Internal API

Internal API (Sometimes called Private API), as the name suggests, is an API that software teams build to cover the needs of specific developers within the same organisation. They’re often part of a more significant effort to develop a bespoke software solution in-house by companies.

Internal APIs have the following characteristics:

• They may or may not be available via the internet.
• They are tailored to fit specific needs.
• The documentation may not be as complete as a public API
• They may or may not practice standard best practices in API development
• API developers don’t enforce rate-limiting

Some examples of Internal APIs are:

• A team at an insurance company builds an internal API to serve customer information for other developers within the organisation to use
• API to export/import data between two internal systems
• API to authenticate and authorise employee access to various internal systems of a bank based on their position.

### Partner API Partner APIs are often associated with commercial software & SaaS products, or the API itself can be a product of an API-first company. To access Partner APIs, one should apply to get access, often by signing up for a service or signing an agreement. When a vendor grants you access to their Partner API, you will get an API key to use their API and will be able to read the API documentation online.

Partner APIs are one of the key contributors to the growth of SaaS products from the user-base and revenue perspective. For example, a company can offer API to:

• Promote API as an advantage over competitor products to acquire new customers
• Acquire new customers through integrations with other SaaS products. For example, a customer of a marketing platform signs up for a Twilio (SMS provider) account to automate marketing SMS messages.
• Enable existing customers to extend features of the platform via APIs
• Allow customers to integrate internal tools with SaaS products for a seamless user experience.

Some examples of Partner APIs are:

• Stripe (a payment gateway) allows users of their platform to create monthly subscriptions using API.
• Twilio (SMS provider) allows users to send SMS via API
• AWS (Major cloud computing provider) enables users to provision new servers using their API.

## API types by architecture We can categorise APIs into different types based on the architecture used by software teams to build them. This section will go through the three most popular and widely used types of API from the architectural point of view: REST, GraphQL and SOAP.
### RESTful API **REST** (Representational State Transfer) is a term used by Roy Fielding in 2000 to describe an architecture style for the design of software applications, emphasising leveraging the HTTP protocol. **Restful API** (sometimes called **REST API**) is a type of API that follows the REST architecture style.
### Resource “Resource” is one of the key concepts in REST architecture. **Resources are the data models that the RESTful API serves to the users.** User, product, comment and album are examples of resources in RESTful APIs. Each resource is available via a unique URL.
### Actions REST architecture uses HTTP methods (GET, POST, PUT, DELETE) to read, create, update and delete resources. For example, to create a new customer in Stripe, developers should send a POST request to the api.stripe.com/v1/customers URL. On the other hand, developers can send a GET request to the api.stripe.com/v1/customers/{customer-id} URL to fetch customer information.
### Errors REST architecture uses standard HTTP Status Codes as part of the response to communicate the success of the requested operation. For example, Stripe API returns the 404 error when the requested customer does not exist in your account.
### REST API Pros - Software teams can use HTTP-based infrastructures like web and cache servers easily. - RESTful APIs are easily cacheable. - Gentle learning curve for users of REST API (Mobile & Web developers) - Wide range of developer tools - Rich learning resources and books - Easy to rate-limit users - It fits into the microservice architecture very well. - JSON & XML data format support
### REST API Cons - Lack of batching concepts may result in slow UIs due to multiple HTTP requests. - Fetching unnecessary & redundant data - Limited to the HTTP protocol
### GraphQL API Facebook introduced **GraphQL** language specification in 2015 after various teams successfully used it internally. As the name suggests, **GraphQL APIs leverage the graph concept to represent data.** Using this concept, users of an API can easily explore the graph and query for the data they need.

As we mentioned earlier, REST APIs come with major downsides: lack of batch data fetching capabilities and the problem with unnecessary data fetching. GraphQL, in particular, solves the two shortcomings of REST API.

### Batch Data Fetching Capabilities Lack of batch data fetching in REST results in multiple HTTP requests from the client-side to the server for bringing the required dataset. Let’s say a mobile application needs to display a profile of a user, including her favourite artists. In a REST architecture, the mobile app should send at least two requests: one for the user profile and one for the favourite artists. **The more HTTP calls an app has to send to gather the needed information, the slower the app becomes.** The introduction of HTTP 2.0 and Keep-alive capabilities improved the performance of apps that require multiple HTTP calls, but the underlying problem is not 100% solved. **GraphQL, on the other hand, allows you to combine multiple queries into one single and fetch the data via a single request, a solution that solves the batch data fetching problem altogether.**
### Rich Query Capabilities Due to the limited query capabilities of REST APIs, developers have to retrieve the entire resource data where they might only need a small portion of the dataset. In our user & favourite artist examples, the API returns the complete artist profile, whereas we simply need to have the artist’s name and profile picture to render on screen. **GraphQL’s rich query capabilities allow you to request what is needed and only receive that dataset.**
### GraphQL API Props - Self-documented APIs with strong type definitions for objects - Streaming capabilities for real-time applications - Query batching - Optimised data fetching / Powerful data query capabilities - JSON & XML data format support
### GraphQL API Cons - Difficult to cache, developers cannot use standard HTTP caching solutions. - Steep learning curve for mobile & web developers - Difficult to rate-limit - Challenging to fit into the microservices architecture
## SOAP API **SOAP** (Simple Object Access Protocol) is a protocol to send and receive messages in XML format. SOAP APIs leverage the SOAP messaging protocol to receive requests from the clients and respond to them. SOAP APIs are accessible via application-level protocols like HTTP and TCP. Although SOAP APIs are not the choice for companies with Open API or Partner APIs, SOAP API is widely used within enterprises to build Internal APIs.
### Action Centric Unlike REST & GraphQL, which are centralised around the data (resources, types), SOAP APIs are centralised about actions. **In SOAP APIs, a client triggers an action (Get User, Get Favourite Artists), and API fulfils the request.**
### Variation of RPC Bruce Jay Nelson coined the term Remote Procedure Call (RPC) in 1981 as a way for one computer program to run a piece of code that is hosted on another machine remotely and get the results. RPC was one of the core components of distributed computing in 80 and 90s. SOAP APIs can be considered a form of RPC that use the SOAP messaging protocol to send the execution requests and receive results.
### SOAP API Pros - Access through various application-layer protocols, including HTTP, SMTP, TCP & UDP - Standardised messaging protocol
### SOAP API Cons - Only supports XML as data format. - It cannot use HTTP caching as it uses the POST method to send messages.
### Consider API Users When deciding on what type of API to build, it’s also essential to consider APIs’ users (general public, developers within an organisation or partner companies) as their requirements impact the type of API you build for them. Below are some examples:

• Open APIs primarily serve static data and have many hits daily. REST APIs support caching very well, making an excellent choice for Open APIs to tackle the scalability challenges of a high traffic API.

• Many developers use open APIs; most programming languages offer a great range of libraries to work with REST APIs, making REST an excellent choice for Open APIs. Moreover, most developers have experience using REST APIs, making integration with any REST API easy.

• GraphQL is an excellent fit for Internal APIs with lots of query & mutation needs.

## FAQ ##### What is a legacy API? Legacy API is a term used to describe an API that users are using for many years. Often the term legacy means there will be a successor API to replace the Legacy API.
##### What makes an API legacy? APIs become legacy for many reasons but primarily because of using programming languages that are not popular anymore, using technologies in maintenance mode and sometimes because of poor design decisions.
##### How to pick the best type for a new API? Consider the following items: - The user of the API - Caching requirement - Talent to build the API - Open-source libraries to leverage
##### What API versioning means? Versions are a common practice when building REST APIs. Versioning allows software teams to introduce new features to their API without causing issues for existing users who use the API. Instead of changing existing endpoints, software developers introduce new endpoints for new features.
##### What Open APIs are currently available? Open APIs are available for different topics. To get an idea, please have a look at [this page](https://github.com/public-apis/public-apis).