An introduction to APIs: Types of APIs, API architecture, & beyond
APIs: A brief history
The first Application Programming Interface (API) was implemented in a Univac 1108 in the 1970s. Salesforce launched its API — which was the first modern API — on February 7, 2000. Since then, we’ve seen a tremendous explosion of the SaaS industry. SaaS has grown around 500% since 2016 and is estimated to be worth more than $195 billion. According to BetterCloud’s State of SaaSOps report, companies with under 50 employees use 16 different SaaS systems, while companies with 1,000+ employees use a staggering 177 different SaaS tools.
All of these software systems and tools need to integrate and communicate, and this is where different types of APIs come into play. But what is an API? Put simply, an API is a mechanism by which software systems can communicate with each other on the basis of pre-defined API protocols, definitions, and standards. The type of API used, and also popular API architecture like the SOAP API, have a significant effect on the form and function of the apps we use every day.
In this post, we’re going to explain four different types of APIs: open APIs, internal APIs, partner APIs, and composite APIs. We’ll also examine three different API architecture protocol types: REST APIs, RPC APIs, and SOAP APIs.
What are the 4 major types of APIs?
Understanding the different types of APIs and the situations each is best suited for will help your software development team operate more efficiently. These 4 types of APIs have been scoped according to the level of availability for developers. Let’s examine each type of API and work through some details and use cases.
What are open APIs? Also known as public APIs or external APIs, open APIs are publicly available and many are free to use. Some charge a fee that’s typically based on usage or a subscription model.
For example, YouTube offers a free open API that allows developers to bring the functionality of YouTube (playing a video, liking a video, commenting on a video, etc.) into their own application. An open API allows you to share data without limitation and encourages other organizations to integrate with the company that owns the open API. The only limitation of these APIs are usage limits.
Security is also a factor for open APIs — hackers can theoretically gain access to networks and computer systems through open APIs and perform various attacks such as man-in-the-middle (MITM), distributed denial-of-service (DDoS), injection, or broken access control attacks. There are, of course, multiple different measures API developers can implement to mitigate security risks of open APIs.
ChatGPT is an example of an open API, but it charges for its use. The ChatGPT API costs $0.002 per 1,000 tokens, which is how it calculates usage; 1,000 tokens is about 750 words.
What is an internal API? Also known as private APIs, internal APIs are designed to function completely within an organization’s internal network infrastructure. An internal API connects two or more applications, which are generally also only used within the organization itself without any external functionality.
Internal APIs often don’t have as many security measures built in simply because there is no external access to them.
In general, internal APIs are becoming increasingly rare, as most widely used applications already have an API available for the purpose of integrating into other applications. One downside to internal APIs is that your development team will need to maintain functionality as the internal systems it integrates release new features and updates.
A partner APIs allow companies to grant certain levels of application access externally to other business partners. Because partner APIs serve a specific business purpose, often supported by revenue, companies that grant access to partner APIs enjoy control over who can access their resources, as well as more influence in how their partner API is used.
For instance, the Amazon API is one of the most well-known partner APIs in the world. Amazon grants limited access to its application so that its partners are able to pull and display data such as inventory, shipping estimates, and other logistical info. Since Amazon benefits from the additional sales channels their partner provides, it makes sense for Amazon to offer a partner API to companies that sell products on their behalf.
Partner APIs have strong security in the form of licenses, authentication, and authorization. Generally speaking, partner APIs do not generate revenue in the same manner as open APIs do, but rather their partners pay for the service the API provides.
Lastly, we have composite APIs, which combine multiple APIs into a single operational process. This allows developers to bundle their API calls while also only receiving one response from multiple different servers. This allows for reduced server load and faster systems. Composite APIs are frequently used in microservices architectures.
Shopify uses a composite API because part of its normal app function is to integrate with multiple other marketplaces like Amazon, Etsy, eBay, and more. Rather than manage all those different endpoints, a composite API allows the developer to only need to support one API.
This is not only beneficial from a security standpoint, but it also creates performance enhancements with the speed that data can be processed from multiple sources with a single call and response sequence.
What are the types of API architecture & communication protocols?
In addition to the four types of APIs we covered above, it’s also important to understand different communication protocols that an API can operate within. So what is API architecture? An API architecture or protocol can be thought of as a set of rules that determine which types of information can be shared with clients, how the information can be shared, and which operations can be conducted.
API protocols are also referred to as API architecture because API architecture dictates which type of code you can use, such as XML, JSON, Python, etc.
REST API: Representational State Transfer
The vast majority of web APIs are built with the REST (Representational State Transter) API architecture standards. So what are REST APIs? Sometimes called RESTful APIs, these APIs are designed to transfer data from a server to a requesting client. REST APIs are scalable and lightweight. In general, developers like using the REST API protocols because they are:
Simple to use: Largely considered the easiest API architecture to use, REST requires developers to use the HTTP protocol, which means communication is text-based and uses request methods most developers already know - such as GET, POST, PUT, and DELETE. Additionally, REST APIs use a uniform interface, so once you learn how to use it you can operate in a familiar environment moving forward.
Stateless: Each request is processed on the server side and is independent from the previous or next request. This means each transaction is simpler and the server doesn’t have to waste processing power on anything but the current request.
Loosely coupled: The server is separated from the client, and the two cannot modify each other in any way. This allows developers to work on different aspects of the REST API without interfering with the overall function.
Flexible: REST APIs work with several message formats including JSON, HTTP, plain text, and XML. Creative developers can use these formats to create a huge range of functionality without adding too much complexity.
Scalable: Because of the above features, REST APIs work with large applications and huge data sets without losing speed or accuracy. In this way, they can work with virtually any software.
The use cases for REST APIs are basically unlimited, but they are particularly attractive for cloud applications, cloud services, and web use.
GraphQL was developed by Facebook (now Meta) in 2012 for internal use in connecting their applications, and was later released in 2015 as an open source project. As a query language, GraphQL provides a syntax for clients to request data through an API. The purpose of GraphQL is to give developers a complete view of any data stored within an API. GraphQL allows clients to specify their exact data requirements, which helps to reduce over-fetching and under-fetching of data.
In order to build an API with GraphQL, you’ll need your server to host the API and client connecting to an application endpoint. There are three basic components of a GraphQL API:
Schema: This is the type system used to define the API for implementation on a server and includes all its services and functions. It acts as a contract between the server and clients, specifying what data can be requested and how it is structured.
Query: This makes up the request for an output. Developers create queries that are declared with a keyword, which can support arrays, arguments, and nested fields.
Resolver: This function specifies how the API can access data within a given field. This allows the server to know how to handle queries. Resolvers provide the logic to fetch the requested data from the appropriate data source, whether it's a database, an external API, or any other data storage.
One of the main benefits of GraphQL APIs is that they can consolidate multiple endpoints of disparate data into a single endpoint that simplifies complex queries. GraphQL is known for reducing complexity through code organization and object relationships. Developers can enjoy increased predictability and standardization of the data that’s returned from complex queries.
RPC: Remote Procedure Call
Next up we have RPC APIs, which were the first type of API architecture protocol created and also the simplest. One of the main differences between RPC APIs and REST APIs is that RPC is action-oriented, meaning that its primary function is to execute scripts on a server; REST is considered resource-oriented because it’s designed to facilitate data transfer.
RPC APIs lack the standardization that both REST APIs and SOAP APIs offer, potentially adding more variability in how RPC APIs can be executed. RPC APIs use either JSON or XML in their calls. Additionally, RPC APIs are generally considered to be fairly limited in functionality and security; this is one of the reasons they’re infrequently used on the web today.
One advantage of RPC APIs is that due to their simpler nature, they can generally offer high performance. RPC was a precursor to gRPC, an open-source framework initially created by Google that is now used by companies like Cisco, Square, and Netflix.
SOAP APIs: Simple Object Access Protocol
Lastly we have the SOAP API. SOAP is a messaging protocol that defines the XML-based format for exchanging structured information over the web in a distributed environment. With SOAP APIs, developers can exchange information across operating systems and languages. SOAP, initially developed by Microsoft, was introduced in 1998, a year after the release of XML, and it became a W3C (World Wide Web Consortium) recommendation in 2000. SOAP, like REST, is another popular protocol with many potential use cases. There are multiple reasons development teams use SOAP:
W3C standardization: The W3C sets the standards for SOAP APIs, among many other web architectures and languages. These standards help developers maintain quality and uniformity around security, messaging formats, metadata, transactions, etc.
Stateful: Unlike REST, SOAP actually can record previous API calls and use that information for future actions. This can be important for certain situations such as banking transactions.
Distributed systems: SOAP APIs allow communication between different applications running different programming languages. Therefore, structured information can be exchanged in a decentralized and distributed environment.
Independent of an underlying transport protocol: Unlike REST which uses HTTP/S exclusively, SOAP can operate with SMTP, FTP, IBM's MQSeries, or Microsoft Message Queuing (MSMQ). This gives greater flexibility beyond just transferring text-based messages.
There are many use cases for SOAP, but generally, it seems to be preferred when you’re working with multiple parties (such as flight booking), when you need transactional history (such as banking), and when you need strict or immutable logic (such as corporate billing).
SOAP is considered to have a steeper learning curve and a smaller community of developers to draw from. Implementations tend to be a bit more code-heavy than REST. For SOAP APIs, the only acceptable data format is XML. SOAP security is focused on preventing unauthorized access to messages using Web Standards (WS) Security.
Ready to see APIs in action? Deploy the Sendbird API for in-app chat
To recap, we’ve discussed what an API is, the 4 types of APIs (Open APIs, Internal APIs, Partner APIs, Composite APIs), and API architecture (REST APIs, RPC APIs, and SOAP APIs). If you’re ready to start building with APIs, why not try to build in-app chat with Sendbird’s REST API?
Many happy users on SourceForge have given Sendbird an average of 4.7/5 stars. If you’d like to build in-app chat with all the features of a modern messenger without sacrificing control over your data or user experience, start a free trial. There’s a plethora of documentation and tutorials available for you to start building right away. If you want to take your chat app to the next level, you can do so with Sendbird Calls, and Live.
Happy in-app communications building! ✨