The anatomy of a web API

So you understand what web APIs are (or at least, you do if you’ve read our previous post What is a web API and why should you care?). But how do they actually work? What key pieces allow them to facilitate the program-to-program conversations behind the Internet of Things (IoT)?

In this post, we’ll break down each of a web API’s three main components: functions, protocols, and transports.

For our purposes, think of a web API as a code-based Russian nesting doll comprised of three layers, each built around the other. Each layer is necessary for the web API to facilitate an IoT conversation.

Functions: The Code Worth Sharing

The innermost layer, the heart of the web API, is the actual, defined program function (or, more often, functions) you’re providing access to. Simple examples include a chunk of banking software code that returns a user’s account balance, or the piece of Google Maps’s programming that returns GPS coordinates. A function is the software component you want to expose to the outside world, so other programs can get information or trigger an action from your system.

Note that a web API is only as useful as the function(s) it calls. Remember, APIs facilitate program-to-program conversations. Just as a regular conversation is only as worthwhile as the person you’re speaking with, an API-facilitated conversation is only as worthwhile as the function you’re calling. This is one reason that some API providers can charge a premium for access to their APIs, while others make theirs available for free.

Protocols: The Rules of Conversation

Now that we have a function to talk to, we need to define the rules of conversation. That’s where the web API’s protocol comes in. Functions are written in a variety of languages (C#, Java, VB, etc.), which is part of what makes a program-to-program facilitator necessary. One of a web API’s primary roles is “translating” the conversations between outside programs and the function the API calls into, so both sides can understand each other regardless of language. The API’s protocol is the collection of standards that makes this “translation” possible.

But while “translation” is the easiest way to explain what a protocol does, it’s not the most accurate. It’s more precise to say that a protocol makes both requests and responses “language neutral”. This is akin to referring to someone by name in a regular conversation. No matter what language you speak, the person’s name remains the same. It is language neutral. So too, are the requests and responses made through a web API, thanks to the API’s protocol.

However, even this analogy begins to break down when you consider that there are a number of different protocols, including JSON-RPC, SOAP, REST, and more. Each protocol “neutralizes” requests and responses slightly differently, making some web API-based interactions difficult. (Thankfully, products like Thriftly exist to help you overcome this barrier!)

Transports: The Medium for the Message

The final layer of a web API is its transport. If a function is the part of a program a web API lets you speak to, and a protocol defines the rules of conversation, then the transport is the medium through which you conduct the conversation. Just as words must travel through air, and phone calls are routed through a phone network, program-to-program conversations need a medium to send data through.

All web API-based conversations are conducted over the Internet, but that statement’s not quite exact enough for our purposes. Different transports send data over the Internet in different ways, each of which provides advantages and disadvantages. If you’ve looked at your web browser’s address bar, you’ll recognize the most common web API transport: HTTP.

HTTP (short for Hypertext Transfer Protocol) typically beats out other transports, including TCP, JMS, and WebSocket, because it was invented specifically for the web, and it’s easy to use. It can also be implemented securely as HTTPS (or Hypertext Transfer Protocol Secure), which adds a layer of encryption on top of the typical HTTP transport method. These days, most web browsers use HTTPS as their transport method.

Conclusion

With a function, protocol, and transport in place, and our nesting doll assembled, we’ve described a working web API! You have an exposed function, standards for sending information to and from that function, and a medium for requests and responses to travel through. These three building blocks are what make the web-based conversations of the Internet of Things possible.

Learn how to transform your Windows Desktop Applications into
Hybrid Cloud Applications with Thriftly.io