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.

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.

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.