When many systems designers create an API spec, they often take the approach of simply “making everything available”. We are huge fans of this approach, and believe in many cases it is an elegant and simple way to enable integrations. The underlying technologies should be carefully considered, as well as the expertise of the staff who must execute and subsequently maintain the systems.
Security, of course, should be carefully considered – however, a lot of issues can be solved simply by segmenting a private network just for your application. This can not only solve security issues, but proper application isolation can prevent latency issues in networks that require predictable communication throughput. Why take a chance sending your traffic on a network with people downloading files, streaming music, and lord knows what else? An isolated network can guarantee your app traffic makes it through quickly and reliably.
Once a network is set up and communication protocols are decided (by the way; we at BLEvolve are huge fans of using REST and HTTP for “spoke-hub” communications and TCP for peer to peer) – you will want to decide a message structure. As a start, and because of the proliferation of libraries out there, if you can handle a bit of wiggle room for extra mark up data, you can accomplish a lot in short periods of time using an HTTP client-server architecture with XML or JSON (which we recommended). Binary formats such as MessagePack and the Google-backed Protobuf are very good (if compression and speed are your primary consideration); However, these increases in throughput often come at the cost of flexibility. Most binary formats will require you to “mark up” your messages, and changing the mark up from version to version can cause upgrade issues if not handled carefully and competently. This task can be non-trivial for an engineer/developer unfamiliar with the format, or unfamiliar with the data itself.
We typically recommend JSON over XML because we think it is a bit easier to read, nearly always is faster for to process, and in many cases offers object sizes ~50% that of XML interchange (using the same data). Let’s take a sample JSON output from a webservice, and the equivalent XML:
"tag_id": "Agilent Mainframe C",
The resulting XML payload is twice the size:
<?xml version="1.0" encoding="UTF-8"?>
<tag_id>Agilent Mainframe C</tag_id>
The proliferation of great free and open source JSON processing libraries – such as JSONJoy (our product Asset Beacon uses this in the mobile client) and JSON.NET – makes using JSON easy even for novices, and helps to ensure your data gets from integration point A to integration point B with an absolute minimum of fuss.