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.
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 principal types of API commonly used in web-based applications: 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.
Public APIs typically involve moderate authentication and authorization. An enterprise also may 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 may 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 may 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. SOAP is also extensible and style-independent, which allows 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 may contain up to four components, including an envelope, header, body and fault (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 may be easier to code and maintain, but might not offer the level of security, such as encryption, 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.
|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 to exchange and the required level of security. JSON is the simpler language, and JSON-RPCs support only alphanumeric data (text) exchanges with little security. XML-RPC handles a wider range of data, including text, images, graphs and 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 may 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.