There are various types of APIs, the most popular of which is Web API––otherwise known as a Web Service. A Web API provides an interface for Web applications, or applications that need to connect to each other via the Internet to communicate. Web APIs have exploded exponentially, reaching over 17,000 in 2017. There are four popular subcategories of Web APIs, including SOAP, XML-RPC, JSON-RPC, and REST.
SOAP
SOAP was designed in 1988 by Dave Winer, Don Box, Bob Atkinson, and Mohsen Al-Ghosein for Microsoft Corporation. It was designed to offer a new protocol and messaging framework for the communication of applications over the web. While SOAP can be used across different protocols, it requires a SOAP client to build and receive the different requests, and relies heavily on the Web Service Definition Language (WSDL) and XML:
<?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http://www.w3.org/2001/12/soapencoding"> <soap:Body xmlns:m="http://www.example.com/weather"> <m:GetWeather> <m: ZipCode>94108</m:ZipCode> </m:GetWeather> </soap:Body> </soap:Envelope>
In its early years, SOAP did not garner strong support in all languages, and it often became a tedious task for developers to integrate SOAP using WSDL. However, SOAP calls can retain state, something that other types of APIs (e.g. REST) are not designed to do.
XML-RPC
Remote Procedure Calls, or RPC APIs, are quicker and easier to implement than SOAP. XML-RPC was the basis for SOAP––although many continued to use it in its most generic form, making simple calls over HTTP with the data formatted as XML.
However – similar to SOAP – RPC calls are tightly coupled and require the user to not only know the procedure name, but often the order of parameters as well. This means that developers would have to spend extensive time going through documentation to utilize an XML-RPC API. Further, keeping documentation in sync with the API is of utmost importance, otherwise a developer’s integration attempts are futile.
JSON-RPC
The JavaScript Object Notation was introduced by State Software, Inc. in 2012 and popularized by Douglas Crawford. The format was originally designed to take advantage of JavaScript’s ability to act as a messaging system between the client and the browser (think AJAX). JSON was then developed to provide a simple, concise format that could also capture state and data types, allowing for quick deserialization.
Yahoo started taking advantage of JSON in 2005, followed by Google in 2006. Since then, JSON has enjoyed rapid adoption and wide language support––becoming the format of choice for most developers.
You can see the simplicity that JSON brought to data formatting by comparing the following line with the SOAP/XML format above: {“zipCode”: “94108”}
Still, while JSON presented a marked improvement over XML, the downsides of an RPC API exist, most prominently tightly coupled URIs.
REST
REST or RESTful APIs are the most popular choice for API development. These APIs are designed to take advantage of existing protocols. While REST can be used over nearly any protocol, it typically takes advantage of HTTP when used for Web APIs. This means that developers do not need to install libraries or additional software in order to take advantage of a REST API.
REST also provides an incredible layer of flexibility. Since data is not tied to methods and resources, REST has the ability to handle multiple types of calls, return different data formats and even change structurally with the correct implementation of hypermedia. Unlike SOAP, REST is not constrained to XML; instead, it can return XML, JSON, YAML, or any other format depending on what the client requests. In contrast to RPC, REST users aren’t required to know procedure names or specific parameters in a specific order.
However, you also lose the ability to maintain state in REST (e.g. within sessions) and it can be more difficult for newer developers to use. It’s also important to understand what makes a REST API RESTful, and why these constraints exist before building your API. If you do not understand why something is designed in the manner it is, you are more likely to disregard certain elements and veer off course.
To learn more about the types of APIs and, in particular, REST APIs. Read our eBook Undisturbed REST, a guide to designing the perfect API.
