Using Your Verbs In API Design

It doesn’t matter if you are fully embracing RESTful API design practices, at a minimum, you should be using your HTTP verbs in the design of your API. One hurdle which we encounter on a regularly basis trying to turn web APIs into streams, is API designers requiring a POST to simply make basic GET requests. If you are using the web as  transport, everything begins with a GET, no matter whether you are returning HTML or JSON. If you don’t follow this basic rule, it makes it pretty difficult for developers to build on top of your APIs, and it makes it near impossible for service providers like Streamdata.io to be able to help augment your valuable APIs, with meaningful, standardized solutions. Verbs are really important in API design.

Many of the APIs we encounter that use POST, instead of GET for making simple requests, are the result of automated or un-critical transformations of legacy SOAP web services which leveraged HTTP POSTs as its primary method of transport. IT, and development groups are looking to make their services more web friendly, by transforming responses into JSON, yet haven’t put much thought into the overall design of their API, and how the web should be used as a data transport. If you are working on one of these teams, modernizing legacy systems, please study up on the core principles of HTTP, and even look at the basis of REST, while you are at it–your job will be much easier down the road if you invest the time now.

Streamdata.io desires basic JSON APIs, leveraging the most common HTTP verb, GET. While we’d like to support as many types of APIs as possible, this represents the lowest bar we feel we can support. We can take any API that meets this low level of requirements, and turn it into a stream using Server-Sent Events (SSE), with updates delivered as JSON Patch.  If an API requires a body to be submitted instead of query parameters or headers, and only speaks using POST, there is not much we can do to proxy, and deliver a stream from the API. We aren’t alone, most other API service providers will come to same conclusion, and won’t be able to service any APIs that are designed in this way.

We aren’t card carrying RESTafarians at Streamdata.io, but we do appreciate the elegance and simplicity of a well-designed API, that does one thing and does it well. Our team has worked hard to reflect this API philosophy into our service, to help ensure Streamdata.io does one thing, and does it well–turning your JSON APIs into real time streams. To help us do that, we just ask that you make sure you are considering your HTTP verbs when working your API design, and helping make sure your web APIs are as standardized as they possibly can.

image credit: Ecole Polytechnique