By
- Stephen J. Bigelow,Senior Technology Editor
Published: 10 Jan 2023
The API is a powerful and versatile means to connect diverse and disparate software applications. APIs allow a vast array of unrelated software products to integrate and interoperate with other software and data. APIs also allow developers to add features and functionality to software by utilizing a rich array of other developers' APIs. Much of today's enterprise, mobile and web software depends on a wide range of APIs.
APIs are not all equal, however. Developers can work with an assortment of API types, protocols and architectures that suit the unique needs of different applications and businesses.
Four types of web APIs
APIs are broadly accepted and used in web applications. There are four different types of APIs commonly used in web services: public, partner, private and composite. In this context, the API "type" indicates the intended scope of use.
Public APIs. A public API is open and available for use by any outside developer or business. An enterprise that cultivates a business strategy that involves sharing its applications and data with other businesses will develop and offer a public API. These are also called open APIs or external APIs.
This article is part of
Guide to building an enterprise API strategy
- Which also includes:
- 5 major reasons to adopt an API management platform
- 12 API security best practices to protect your business
- API testing checklist and best practices
Public APIs typically involve moderate authentication and authorization. An enterprise also might seek to monetize the API by imposing a per-call cost to utilize the public API.
Partner APIs. A partner API, only available to specifically selected and authorized outside developers or API consumers, is a means to facilitate business-to-business activities. For example, if a business wants to selectively share its customer data with outside CRM firms, a partner API can connect the internal customer data system with those external parties -- no other API use is permitted.
Partners have clear rights and licenses to access such APIs. For this reason, partner APIs generally incorporate stronger authentication, authorization and security mechanisms. Enterprises also typically do not monetize such APIs directly; partners are paid for their services rather than through API use.
Internal APIs. An internal or private API is intended only for use within the enterprise to connect systems and data within the business. For example, an internal API might connect an organization's payroll and HR systems.
Internal APIs traditionally present weak security and authentication -- or none at all -- because the APIs are intended for internal use, and such security levels are assumed to be in place through other policies. This is changing, however, as greater threat awareness and regulatory compliance demands increasingly influence an organization's API strategy.
Composite APIs. Composite APIs generally combine two or more APIs to craft a sequence of related or interdependent operations. Composite APIs can be beneficial to address complex or tightly related API behaviors and can sometimes improve speed and performance over individual APIs.
API protocols and architectures
APIs exchange commands and data, and this requires clear protocols and architectures -- the rules, structures and constraints that govern an API's operation. Today, there are three categories of API protocols or architectures: REST, RPC and SOAP. These might be dubbed "formats," each with unique characteristics and tradeoffs and employed for different purposes.
REST. The representational state transfer (REST) architecture is perhaps the most popular approach to building APIs. REST relies on a client/server approach that separates front and back ends of the API and provides considerable flexibility in development and implementation. REST is stateless, which means the API stores no data or status between requests. REST supports caching, which stores responses for slow or non-time-sensitive APIs. REST APIs, usually termed RESTful APIs, also can communicate directly or operate through intermediate systems such as API gateways and load balancers.
RPC. The remote procedural call (RPC) protocol is a simple means to send multiple parameters and receive results. RPC APIs invoke executable actions or processes, while REST APIs mainly exchange data or resources such as documents. RPC can employ two different languages, JSON and XML, for coding; these APIs are dubbed JSON-RPC and XML-RPC, respectively.
SOAP. The simple object access protocol (SOAP) is a messaging standard defined by the World Wide Web Consortium and broadly used to create web APIs, usually with XML. SOAP supports a wide range of communication protocols found across the internet, such as HTTP, SMTP and TCP/IP. SOAP is also extensible and style-independent, which enables developers to write SOAP APIs in varied ways and easily add features and functionality. The SOAP approach defines how the SOAP message is processed, the features and modules included, the communication protocol(s) supported and the construction of SOAP messages.
Compared with the flexibility of REST, SOAP is a highly structured, tightly controlled and clearly defined standard. For example, SOAP messages can contain up to four components, including an envelope, header, body and fault -- the latter used for error handling.
Comparing API protocols
The choice of an API format can have a profound and long-lasting impact on the success and adoption of an API. Organizations must select the most appropriate format based on the complexity of the information that must be exchanged, the level of security needed around that information and the speed or performance required from those exchanges.
For example, a simpler format might be easier to code and maintain but might not offer the level of security that an enterprise adopter requires. More complex formats might provide that security but pose higher learning curves for adopters or require more bug fixes and work from developers. The tradeoff is rarely simple, but there are some common considerations for the major API formats.
Consider REST and SOAP. Both formats are designed to connect applications and mainly utilize HTTP protocols and commands such as Get, Post and Delete. Both can use XML in requests and responses. However, SOAP depends on XML by design, while REST can also use JSON, HTML and plain text. SOAP is standardized with strict rules, while REST allows flexibility in its rules and is instead governed by architectures. SOAP is built from remote procedure calls, while REST is based on resources.
Thus, both REST and SOAP exchange information, but do so in very different ways. SOAP is used when an enterprise requires tight security and clearly defined rules to support more complex data exchanges and the ability to call procedures. Developers frequently use SOAP for internal or partner APIs. REST is used for fast exchanges of relatively simple data. REST can also support greater scalability, supporting large and active user bases. These characteristics make REST popular for public APIs, such as in mobile applications.
| REST | SOAP |
| Works with XML, JSON, HTTP and plain text | Works with XML by design |
| Loose and flexible guidelines based on architectures | Strict, clearly-defined rules |
| Modest security | Advanced security |
| Works well with data | Works well with processes (actions) |
| Uses low bandwidth and is highly scalable | Uses more bandwidth with limited scalability |
The discussion about when to use RPC is a bit simpler. Similar to SOAP, RPC is highly structured and intended for relatively simple APIs capable of invoking processes. The choice then is whether to use JSON or XML -- and again, it depends on the API's intended purpose, the types of information exchanged and the required level of security. JSON is the simpler language, and JSON-RPCs support only alphanumeric data or text exchanges with little security. XML-RPC handles a wider range of data, including text, images, graphs, charts and more. Thus, XML offers superior document handling capabilities and offers better security features than JSON. Both approaches support a variety of programming languages, including Python, Java and PHP.
Ultimately, RPC-based APIs are a poor choice for enterprise-grade APIs because of their limited data type support and limited security. However, they might be suitable for some internal composite APIs. For example, JSON-RPC APIs can make calls without awaiting a response and support multiple simultaneous calls that can be handled asynchronously. The point here is to select an API type that best suits the needs of the business and the applications that must be connected.
Choosing the right API
Whether selecting an existing API for use in a software project or building a new API from scratch, there are several important factors that developers should consider or include, such as the following:
- Clear and complete documentation. APIs are software, and like any software, they require comprehensive documentation that provide developers with how-to guidance, reference usage and example use cases designed to help developers apply the API quickly and successfully.
- Easy adoption. Keep the API simple, establish an easy method of acquiring the API -- such as downloads and account sign-ups -- and ensure solid and knowledgeable API support that can address any developer questions. Otherwise, the API will be too hard or unpleasant to integrate and developers will pass it by in favor of other APIs that are easier to adopt.
- Ease of use. A good API is simply easy to use with sensible and intuitive call structures. Even the most powerful and comprehensive API will be ignored if it uses cumbersome and inconsistent calls and responses. Simplicity, consistency, clarity and backward compatibility -- involving clear deprecation -- are hallmarks of a good API.
- Stability and reliability. Good APIs are developed just like any other software, which should include comprehensive testing for bugs and clear metrics for scalability and performance, such as how many client-server calls per second the API can handle and other relevant factors. Buggy APIs with inconsistent or unreliable performance will quickly be abandoned by developers. APIs used through third-party providers must be highly available and robust.
- Security. APIs must support security through clear authentication -- where only authorized users can use the API. In addition, any data exchanged across the API should be encrypted or otherwise shielded from snooping and theft.
Examples of APIs in use today
APIs are common, and even essential, for the success of many modern software platforms. Everyday computer users might use a wide variety of APIs without ever realizing their importance. Examples of contemporary API use cases include the following:
- Social media APIs. Social media platforms such as Twitter and Facebook rely on APIs to handle communication between the platform and remote endpoints, including functions such as Twitter bots.
- Login and authentication APIs. Today's highly integrated software environments rely on APIs to provide some level of single sign-on For example, one application might ask a user to "log-in using Facebook." This avoids the need for users to create a unique account for every site or application they use, but the API involved effectively integrates the authentication of multiple applications behind the scenes.
- Widget and service APIs. APIs are commonly used to integrate a wide range of small features and functions. For example, the weather report, ocean tide schedule, news feeds and other content that comes up in a web search is typically generated through APIs used by the search engine to varied service providers. Other services such as Google Maps use an API to enable users to search locations or plan routes through their web browser, and APIs also allow maps to be included in countless third-party websites.
- Financial and payment APIs. It's commonplace for a bank to rely on an API to connect remote users to the bank's back-end systems for remote deposits, balance checks, transfers and electronic payments. Large financial businesses such as PayPal use an API to connect a user to a PayPal account and even use PayPal to make payments to other shopping sites, such as Amazon and eBay.
- Travel and booking APIs. Users that search airline schedules and purchase tickets are using the airline's API, while searching for hotel availability and booking rooms employ the hotel's API. Still other sites, such as Trivago and Expedia, use custom APIs to enable users to search and book a wide range of flights and accommodations while the travel site uses airline, hotel, car rental and other provider APIs from the back end.
- Shipping and supply-chain APIs. The process of packing and shipping an item from origin to destination produces a great deal of real-time data. APIs are used to allow customers to check the status of a purchase and see any shipping details, including the current location of the package and its anticipated delivery.
- Content delivery and management APIs. Online content delivery platforms such as Spotify and Netflix rely on APIs to enable users to select desired content and then deliver that streaming content to the user's device for viewing, all while the provider maintains control over the content, which is never actually downloaded or stored on the user's device.
- Microservices. From a software development standpoint, APIs are vital elements of modern microservices-based applications, allowing communication between the many modules or containers spawned to compose the application. Thus, a change can be made to one module, but testing and updating can be confined to that respective module or microservice.
These are typically the most common and recognizable APIs in use today, but there are countless APIs developed for business partners or in-house use that help the business without ever seeing general adoption. As the role of software grows, APIs will continue to find new use cases and play an ever-increasing part of software development.
Dig Deeper on API design and management
API series - Salt Security: Unified monitoring of APIs for seasoned security
By: AdrianBridgwater
(Video) What is an API (in 5 minutes)- SOAP (Simple Object Access Protocol)By: AlexanderGillis
- 22 API management interview questions and answersBy: LindaRosencrance
- REST (REpresentational State Transfer)By: KerryDoyle
FAQs
What are the types of APIs and their differences? | TechTarget? ›
REST API uses web services and is based on request and response, whereas RESTful API works completely based on REST application and infrastructure.
What are the 6 types of API? ›- REST. REST APIs are modern and are the most popular API architecture that developers use. ...
- SOAP. Simple object access protocol (SOAP) is an official API protocol. ...
- GraphQL. GraphQL is a query language for an API. ...
- Apache Kafka. ...
- AsyncAPI. ...
- Remote Procedure Call (RPC)
REST API uses web services and is based on request and response, whereas RESTful API works completely based on REST application and infrastructure.
Are all APIs the same? ›APIs. Though APIs and web services can both facilitate data transfers between applications over the internet, they are not the same, and the terms should not be used interchangeably in every case. The key distinction is that web services are a type of API: All web services are APIs, but not all APIs are web services.
What are the 4 types of API? ›There are four different types of APIs commonly used in web services: public, partner, private and composite.
What are the three basic types of APIs? ›- REST, a collection of guidelines for lightweight, scalable web APIs.
- SOAP, a stricter protocol for more secure APIs.
- RPC, a protocol for invoking processes that can be written with XML (XML-RPC) or JSON (JSON-RPC).
SOAP is a protocol, whereas REST is an architectural style
An API is designed to expose certain aspects of an application's business logic on a server, and SOAP uses a service interface to do this while REST uses URIs.
An open API has access restrictions because they are openly accessible to the public and can be invoked from anywhere on the open internet. On the other hand, a closed API, also known as a private API, is not accessible openly on the internet.
What is the difference between REST and Open API? ›REST APIs use HTTP protocol for data transmission. This protocol allows platforms and systems written in different programming languages to interact. OpenAPI deals with RESTful APIs only, not other types of APIs.
Why is API called REST? ›A REST API (also called a “RESTful” API) is a specific type of API that follows these guidelines. REST stands for Representational State Transfer. This means that when a client requests a resource using a REST API, the server transfers back the current state of the resource in a standardized representation.
What is difference between REST and JSON? ›
While SOAP and REST are both leading approaches to transferring data over a network using API calls, JSON is a compact data format that RESTful web services can use. Deciding whether you should create a SOAP vs REST API is an essential question if you are planning to provide a web service.
What is the main difference between SOAP and REST API? ›Key Difference Between SOAP and REST API
SOAP needs more bandwidth for its usage whereas REST doesn't need much bandwidth. Comparing SOAP vs REST API, SOAP only works with XML formats whereas REST work with plain text, XML, HTML and JSON. SOAP cannot make use of REST whereas REST can make use of SOAP.
- Go to View -> Developer -> Developer Tools to open Chrome's Developer Tools. ...
- After that, select the XHR filter. ...
- After that, you'll need to devote some time to researching the specific request.
- Then, to view the data, go to the preview tab.
Since being introduced by Facebook, GraphQL has taken the API world by storm as an alternative to REST APIs. GraphQL fixes many problems that API developers and users have found with RESTful architecture. However, it also introduces a new set of challenges which need to be evaluated.
What is the difference between API and endpoint? ›It's important to note that endpoints and APIs are different. An endpoint is a component of an API, while an API is a set of rules that allow two applications to share resources. Endpoints are the locations of the resources, and the API uses endpoint URLs to retrieve the requested resources.
What is the opposite of restful API? ›Many authors call the opposite of REST by the name of Remote Procedure Call (RPC). This denotes schemes in which the client and server agree upon a protocol that typically needs to be compiled into both ends.
What is AWS API? ›Amazon API Gateway is an AWS service for creating, publishing, maintaining, monitoring, and securing REST, HTTP, and WebSocket APIs at any scale. API developers can create APIs that access AWS or other web services, as well as data stored in the AWS Cloud .
What is Postman API? ›Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs—faster.
What are the types of API in AWS? ›- Edge-optimized API endpoint.
- Private API endpoint.
- Regional API endpoint.
The western honey bee or European honey bee (Apis mellifera) is the most common of the 7–12 species of honey bee worldwide. The genus name Apis is Latin for "bee", and mellifera is the Latin for "honey-bearing", referring to the species' production of honey for the winter.
Why REST is better than SOAP? ›
Benefits of REST Over SOAP
REST allows a greater variety of data formats, whereas SOAP only allows XML. Coupled with JSON (which typically works better with data and offers faster parsing), REST is generally considered easier to work with. Thanks to JSON, REST offers better support for browser clients.
While REST is faster than SOAP and makes things easier, we have to admit that SOAP is more secure. Both SOAP and REST can use SSL or Secured Socket Layer for protecting the data during the API call request. However, SOAP goes an extra mile and supports Web Services Security as well.
What is the difference between SOAP and JSON? ›Key Difference Between JSON and SOAP
SOAP is a protocol that means a set of rules. JSON is an object. SOAP can use JSON for communication, but the reverse is not at all possible. SOAP uses XML format, whereas JSON uses a key-value pair.
Public APIs are open to anyone and can be used without restrictions. Private APIs are only accessible by authorized users and may be subject to usage restrictions.
What is the difference between GET API and POST API? ›Difference between GET and POST Method in API
No limit on data length is there in POST request. Get is simple to use because of its nature of appending data to URL only. Post requires header information, body, etc which makes it hard to use as compared with Get request. Get requestsrequest can be cached.
API vs Blockchain
A blockchain is about storing and securing sensitive data onto a ledger that gets validated through consensus among network nodes. On the other hand, API is the collection of protocols and data that acts as a base for other developers to modify and create an app.
You can use JSON Schema to describe data objects for both requests and responses. However, OpenAPI includes how those requests and responses are formatted. Similarly, you can mock API responses with JSON Schema, but you need something like OpenAPI to generate an entire mock server.
What is difference between web application and REST API? ›As Web APIs are lightweight architecture, they are designed for gadgets constrained to devices like smartphones. In contrast, REST APIs send and receive data over systems making it a complex architecture.
What is REST API for dummies? ›A RESTful API is an architectural style for an application program interface (API) that uses HTTP requests to access and use data. That data can be used to GET, PUT, POST and DELETE data types, which refers to the reading, updating, creating and deleting of operations concerning resources.
Is REST always JSON? ›Let's start by defining what REST is and is not. For some, REST means a server that exchanges JSON documents with a client over HTTP. Not only is that not a complete definition, but it's also not always true. The REST specification doesn't require HTTP or JSON.
What is REST API in layman terms? ›
A REST API (also known as RESTful API) is an application programming interface (API or web API) that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services. REST stands for representational state transfer and was created by computer scientist Roy Fielding.
Does REST use XML or JSON? ›REST stands for Representational State Transfer. It is a software architecture style that relies on a stateless communications protocol, most commonly, HTTP. REST structures data in XML, YAML, or any other format that is machine-readable, but usually JSON is most widely used.
What does SOAP API stand for? ›SOAP, which stands for Simple Object Access Protocol, is a highly strict and secure way to build APIs that encodes data in XML.
What is a REST API example? ›For example, a REST API would use a GET request to retrieve a record, a POST request to create one, a PUT request to update a record, and a DELETE request to delete one. All HTTP methods can be used in API calls. A well-designed REST API is similar to a website running in a web browser with built-in HTTP functionality.
Is REST stateless or stateful? ›Is REST API stateless or stateful? A. REST APIs are stateless because, rather than relying on the server remembering previous requests, REST applications require each request to contain all of the information necessary for the server to understand it.
Is SOAP a TCP or HTTP? ›SOAP can be carried over a variety of protocols, enabling communication between applications with different programming languages on both Windows and Linux. Works on the HTTP protocol. Even though SOAP works with many different protocols, HTTP is the default protocol used by web applications.
What is a real example of an API? ›Weather data is a popular API example that we come across regularly. Rich weather snippets appear ubiquitous, appearing on all platforms such as Google Search, Apple's Weather app, and even your smart home device.
Does Amazon have an API? ›Amazon API Gateway is a fully managed service that makes it easy for developers to create, publish, maintain, monitor, and secure APIs at any scale. APIs act as the "front door" for applications to access data, business logic, or functionality from your backend services.
How do I know if my API is soap? ›The very basic difference to find out a SOAP and Rest webservice is SOAP have a wsdl file whereas REST does not have. If you get wsdl it means that is a SOAP service.
What are the problems with APIs? ›- The Complexity of API Integration.
- Security Risks Associated With APIs.
- Cost and Time Consumptions of APIs.
- API System Integration Challenges.
What are modern APIs? ›
The modern API is a product and it has its own software development lifecycle (SDLC) consisting of design, test, build, management, and versioning.
What can APIs not do? ›An API Can't Implement its Own Solutions
While we're on the topic of change, it's important to note that an API can't anticipate your next move. If you're ready to transform your current process, don't expect that your present API will simply adapt.
Developers can use almost any modern programming language (like JavaScript, Ruby, Python, or Java) for their own API coding. Most programming languages already come with the necessary software to interact with web APIs, but developers typically install additional packages, or code, for convenience and flexibility.
Who is the biggest API manufacturer? ›- Prudence Pharmachem:
- Mehta API Pvt Ltd:
- Procyon Life Sciences:
- Apollo Pharmaceuticals API Manufacturers India Pvt. Ltd.:
- Megafine Pharma (P) Ltd. Corporate office:
- Coral Drugs Pvt. Limited:
- CTX Life Sciences:
- Basic Pharma Life Science Pvt Ltd:
These Application Programming Interfaces (APIs) are used for instance to exchange information between mobile apps and the respective banks.
What is the difference between open API and REST API? ›REST APIs use HTTP protocol for data transmission. This protocol allows platforms and systems written in different programming languages to interact. OpenAPI deals with RESTful APIs only, not other types of APIs.
What is the difference between open API and public API? ›An open API, also called public API, is an application programming interface made publicly available to software developers. Open APIs are published on the internet and shared freely, allowing the owner of a network-accessible service to give a universal access to consumers.
What are the different types of API authorization? ›There are four types of Authorization – API keys, Basic Auth, HMAC, and OAuth.
Which API is best REST or SOAP? ›REST is a better choice for simple, CRUD-oriented services, because of the way REST repurposes HTTP methods (GET, POST, PUT, and DELETE). It is also popular because it's lightweight and has a smaller learning curve. SOAP, on the other hand, has standards for security, addressing, etc.
What is REST vs SOAP vs web API? ›REST APIs uses multiple standards like HTTP, JSON, URL, and XML for data communication and transfer. SOAP APIs is largely based and uses only HTTP and XML. As REST API deploys and uses multiple standards as stated above, so it takes fewer resources and bandwidth as compared to SOAP API.
Which API is faster SOAP or REST? ›
REST is generally faster and uses less bandwidth. It's also easier to integrate with existing websites with no need to refactor site infrastructure.
What is a REST API for dummies? ›A RESTful API is an architectural style for an application program interface (API) that uses HTTP requests to access and use data. That data can be used to GET, PUT, POST and DELETE data types, which refers to the reading, updating, creating and deleting of operations concerning resources.
What is the difference between private and open API? ›An API provides a way for developers to access the functionality of an operating system, program or other service. Public APIs are open to anyone and can be used without restrictions. Private APIs are only accessible by authorized users and may be subject to usage restrictions.
What is the opposite of open API? ›Internal APIs are the opposite of open APIs in that they are inaccessible to external consumers and only available to an organization's internal developers.
What is the difference between public and private API Gateway? ›Private API gateways can only be accessed by resources in the same subnet. Public API gateways are publicly accessible, including from the internet. An API gateway routes inbound traffic to back-end services including public, private, and partner HTTP APIs, as well as OCI Functions.
What are the two categories of an API? ›- SOAP (Simple Object Access Protocol): This is a protocol that uses XML as a format to transfer data. ...
- XML-RPC: This is a protocol that uses a specific XML format to transfer data compared to SOAP that uses a proprietary XML format.
OAuth 2.0 is a widely used standard for API authentication, since it provides a secure and convenient way for users to grant third-party applications access to their resources without sharing their passwords.
What is the difference between authentication and authorization in REST API? ›Authentication verifies the identity of a user or service, and authorization determines their access rights. Although the two terms sound alike, they play separate but equally essential roles in securing applications and data. Understanding the difference is crucial. Combined, they determine the security of a system.