If you’re a developer who works with APIs, you’ve probably spent a lot of time discussing or debating REST vs. SOAP vs. RPC or other API protocols. Depending on your point of view, you might think that one API protocol is better than another, and seek to use that protocol whenever possible.
But what if I told you that you didn’t have to choose a single protocol? What if you could write an application that supports multiple protocols at once, thereby catering to the preferences of different developers while also — and this is most important — maximizing interoperability with other services?
Well, you can. By taking advantage of Thriftly’s support for multiple API protocols, you can use whichever protocols work best for you, at the same time. And you don’t even have to write protocol-specific code, because Thriftly handles that tedium for you.
I explain how in this article.
Introducing Bitfire Safety
In order to ground this discussion of multiple API protocols and Thriftly in a real-world use case, let’s pretend that we are designing a solution that caters to the needs of a company I made up called Bitfire Safety.
Bitfire Safety is a fictional fire protection company. Bitfire Safety provides dry pipe sprinkler system installations for customers that own cold-climate structures, such as parking garages. These systems are installed and configured with a command panel system interface and software that is used to locally monitor and test various aspects of the system.
As part of a modernization initiative, Bitfire Safety is enhancing their services to include remote monitoring and issue remediation. They are first concentrating on the monitoring of the supervisory pressure switches. These switches are responsible for ensuring the proper system pressure and will pump or release pressure through a ball valve to maintain the correct levels.
Through monitoring, Bitfire Safety can identify when pressures are tracking low or high. Low pressures could be indicative of an air compressor failing or a leak in the system; pressures tracking high could lead to damaging clappers and gaskets in the system, and could pose a safety risk in the event of a fire where open clappers would just bleed off system air rather than delivering water to a fire.
If the customer desires remote remediation services, they are provided with slightly modified system software from Bitfire Safety that exposes methods that allow for the initiation of a system test, increase of pressure, and release of pressure as a Thriftly service.
Where does support for multiple API protocols factor into all of this, you ask? The answer is that the customer base for Bitfire Safety is made up of mainly large corporate entities, each with their own SOA standards. Bitfire Safety, therefore, needs to be able to work with whichever protocols its customers use.
Luckily for Bitfire Safety, they are already hosting their services with Thriftly, meaning their customer systems can integrate using the API protocol of their choice. Let’s take a look at how they do this.
Service Implementation
To explain how Bitfire Safety hosts their services, we will walk through a demonstration of the creation of a couple of stub services responsible for gathering pressure telemetry data, as well as initiating a remote procedure call to release pressure on the customer’s sprinkler system. The source code for the services can be sourced from your existing code base or written as methods in a new application. Thriftly simplifies development of services by providing an attribute — ‘PublishedAttribute’ that allows you to expose methods as a service.
The telemetry service
The telemetry system is hosted at Bitfire Safety HQ. It expects very high usage, and must be scalable to service multiple customers simultaneously. The optimal protocol for this service would be THRIFT-Binary or THRIFT-Compact, although the other protocols are also supported by the Thriftly infrastructure. The customers use a configuration file for their system software to indicate which API protocol to utilize when integrating with the telemetry service so that their internal technology standards are adhered to.
using System;
using Thriftly.Server;
namespace BitfireSafety.Console.BL
{
public class TelemetryReceiver
{
[PublishedAttribute]
public bool ReceiveTelemetryData(SystemPressureTelemetry inbound)
{
var ack = true;
ForwardToAnalytics(inbound);
ForwardToDataWarehouse(inbound);
return ack;
}
private void ForwardToAnalytics(SystemPressureTelemetry inbound)
{
//todo: send to analytics/monitoring system for hot storage
}
private void ForwardToDataWarehouse(SystemPressureTelemetry inbound)
{
//todo: send to data warehouse for historical cold storage
}
}
public struct SystemPressureTelemetry
{
public int CustomerID;
public int SystemID;
public DateTime TimeStamp;
public decimal SystemPressure;
}
}
Once published to Thriftly, you can obtain WSDL, WADL and IDL definitions for the service by opening a browser to the endpoint of the service and appending: ?wsdl, ?wadl, or ?idl to the URL. These service definitions will make it possible to consume services using various client technologies.
The pressure release service
The pressure release service is hosted on the client site. Their system software is currently exposing an endpoint through a Thriftly gateway that will initiate the pressure release on the sprinkler system. This code is not expected to be called often, so performance is not an upfront concern. The JSON-RPC protocol fits the bill nicely, though as previously specified, other protocols are supported as well.
using System;
using Thriftly.Server;
namespace BitfireSafety.Panel.BL
{
public class ReleasePressureAction
{
[PublishedAttribute]
public PressureReleaseResponse ReleasePressure(decimal psi)
{
//todo: initiate system to release pressure
return new PressureReleaseResponse { PressureReduced = 42.14m, Timestamp = DateTime.Now };
}
}
public struct PressureReleaseResponse
{
public decimal PressureReduced;
public DateTime Timestamp;
}
}
Testing APIs Using Various Protocols
Once the services are published on Thriftly, it is quite easy to test HTTP-based protocols via a built-in Test API web page for your service. One of Bitfire Safety’s customers requires the use of SOAP when transmitting telemetry data. We can utilize the test web page to test that protocol.
You are able to manipulate the data to send and view the response.
Clicking on the Raw button will allow you to see exactly what was passed into the server.
Let’s now use the test interface to exercise the Release Pressure command on the customer system. Because this is a remote procedure call, JSON-RPC is the best-suited protocol for this customer. Like before, click on the Test API, and in the protocol drop-down, this time select JSON-RPC. Send a test request and view the response.
Click on the Raw button in the upper right of the window and view the raw request and response.
You will notice in the headers of the raw requests that there is a Server-Protocol header. This is the header that Thriftly uses to determine the protocol to use for the service call.
Conclusion
In this article, we investigated various protocols that clients can use when you host your services with Thriftly. We saw how supporting multiple protocols is beneficial when consumers of your services are required to adhere to certain internal standards.
This article demonstrated how easy it is to write and host code through Thriftly without having to write any protocol-specific handling code. We utilized the built-in web service test pages to test our services using a couple of different protocols and reviewed the raw request data sent into the server, and the raw response coming back.
If you’re interested in developing expert technical content that performs, let’s have a conversation today.
