Carey Payette
Carey Payette
March 19, 2019

Supporting multiple API protocols with Thriftly

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 (Service Oriented Architecture) 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

Thriftly service implementation example

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.

Thriftly telemetry service example


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.

testing various protocols with Thriftly

You are able to manipulate the data to send and view the response.

view the response in Thriftly


Clicking on the Raw button will allow you to see exactly what was passed into the server.

Thriftly view raw request

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.

Thriftly JSON response

Click on the Raw button in the upper right of the window and view the raw request and response.

Thriftly raw request server-protocol header

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.

Interested in trying Thriftly for yourself? Check out our free-forever developer plan:

New Call-to-action


Editors note: This post was originally published on CodeProject; this version has been slightly modified. 
 

comments
0