Finding efficient ways to process, share, and reuse functionality and data is crucial – it’s an important way to break down monolithic applications into more consumable and maintainable microservices.
In today’s API-focused world, this translates into multiprotocol development (gRPC, GraphQL, EDAs, etc.) and an enhanced development process (governance, standards, design-first). To understand this, we need to look more closely at protocols.
Why are protocols such a big deal?
We went from RPC to SOAP to REST, and found new forms of RPC, GraphQL, and more, for both synchronous and asynchronous services. Even today, in niche areas, these protocols can’t fulfil all the requirements an application needs. It’s important to exploit the benefit of specific protocols for different services in a microservices architecture. Here are the ones you hear about most often.
SOAP (Simple Object Access Protocol)
These days, talking about SOAP services usually gets one of the following reactions:
1. Massive cringe
2. “Why are we talking about hygiene?”
SOAP was immensely powerful in its time, though. Without it, we wouldn’t have faced the challenges which led to the protocols we use today.
SOAP became popular in part because it natively came with a document called Web Service Description Language (WSDL). This described the entire service in an XML format. Although its ability to be read by humans was arguable, at the time it was better than anything provided by any existing API or service.
The WSDL defined many aspects of the service. The schemas helped define and understand what the request and response message should look like, in accordance with the service implementation. SOAP Request and Response messages were always written in XML, and structured like an envelope:
The straightforward message is included in the <SOAP Envelope> which contains <SOAP Header> and <SOAP Body>.
The <SOAP Header> routes messages through a node for additional application process, such as encryptions and other webservice security authentication. It’s built into the SOAP protocol, though using it isn’t mandatory. This makes it easier to secure APIs and services.
The <SOAP Body> is the meat of the request, usually identifying what the request wants to get back from the servers. Here’s an example of a currency converter service.
Request:
Response:
Even in a simple example, there are over 300 bytes in each message. Messages become even heavier for more complex operations. The industry quickly learned that SOAP’s performance wasn’t optimal.
REST (Representational State Transfer)
REST APIs and services are preferred because of their flexibility and improvements over SOAP services. REST supports JSON format, which reduces the bytes needed for a message.
The use of HTTP standards makes it easy to implement and consume RESTful APIs and services. By using HTTP verbs such as GET, POST, PUT, and DELETE, as well as resource path orientation, users find it easy to build APIs and drive simple practices like CRUD operation. Here’s a sample RESTful API call:
Request:
Response:
This creates a new “Pet” for a petstore API by providing Pet information in JSON format. The API returns a 201 or 200 HTTP status code message, indicating the transaction was successful, and returns the JSON data that was posted. Depending on the implementation, there may be additional data received as JSON.
This is an oversimplified version of a simple REST transaction. APIs can be more complex. Imagine trying to put together an integration to this API for a grooming pet website. How do you delete current pet entries? The delete method is simple enough, and we already have the resource from our previous interactions /v2/pet/{petId}, and it may require the same JSON payload, but we can’t be entirely sure. This is where documentation comes into play.
Although there have been many contenders, including WADL, RAML, and API Blueprint, the clear winner is OpenAPI Specification (OAS), previously known as Swagger. OAS provides a great and easy way to document REST APIs to ensure adoptability.
In OAS, the entry deleted above has a natural and human readable format:
Raw OAS:
Human Readable format:
With OAS, you can easily identify what operations are available and what data and metadata is required to execute the operation. This is why REST is so powerful. However, its drawbacks are similar to SOAP’s liabilities.
Consumption of a REST API or service is easier, but performance isn’t optimal, especially when we start getting into the microservices spectrum. JSON uses fewer characters to achieve similar data interchange goals than XML, but it still uses US-ASCII characters, which use more bytes than is optimal.
gRPC (“g” Remote Procedure Call)
gRPC is the newest form of remote procedure calls, introduced by a Google team in 2015. gRPC aims at being a language-agnostic lean RPC. It provides tools to accelerate development in the microservices architecture spectrum.
gRPC supports protobufs (Protocol Buffers), a Google open source mechanism designed to simplify serialization and deserialization of structured data. But protobufs go much further than that – they help in the auto-generation of boilerplate code that accelerates the implementation process. This allows developers more time to create business logic.
The example below has two simple defined messages. These differ from typical REST JSON messages. Instead of having key and value pairs, they have a defined message with datatype, the data (the key of value pair), and a field number. The field number serves as an identifier for the particular piece of data and identifies the value once the message is serialized. Protobufs declare simple rules to determine how to serialize the data at runtime.
Here's an example of some auto-generated code for the “UserName” message above in JavaScript. gRPC supports many languages in addition to JavaScript. The ”Username ” object was created, along with some setters and getters.
gRPC has many advantages, including accelerated transactions due to its serialization capability, and auto generation of code for quicker implementation. These characteristics make gRPC a perfect candidate to support internal microservice communication. However, the complexity of gRPC complexity makes it difficult to be considered for a public-facing API which has a goal of exposing data or functionality.
For more information about how data is serialized in protobufs, see here. If you’re interested in learning more about JSON versus protobuf performance, try this well-researched article.
Don’t miss our on-demand webinar, Best Practices for Expanding Your API Strategy Beyond REST featuring Forrester’s David Mooter.
About the Author:
Temil Sanchez is a product manager responsible for driving product roadmap and optimizing each component of the development lifecycle. For ten years, Temil has focused on creating best API practices in testing, development, and design via roles in QA, support, solutions engineering, and product. He brings a great perspective to the API lifecycle and its future.