Seriously, we can build better web API clients

We are in the era of Software as a Service and microservices. From the techinical point of view this means we are writting more web APIs than we use to, at least in a quantitative sense. This also means we need to build clients (API wrappers) to free our souls from dealing with bare HTTP, and I get this, there are a lot of small tweaks involved in a API call that we don't want to be dealing with every time a request is being made. But this also doesn't mean that our clients need to separate us this much from HTTP.It’s 2015, we are not using RPC anymore (I know, I know some of us still have to deal with legacy APIs, but there’s rarely a reason for someone to write a new RPC based API), most APIs are now RESTful, REST based, RESTish, or at least use some HTTP methods. Well, all programming languages have some kind of requests library but most wrappers keep forcing us to learn a new interface to make requests. And yes, that’s all REST API calls are, HTTP requests, trust me, they are not that complicated. Things get even worse when wrappers simply destroy the RESTfulness of APIs. People think it’s cool to write complex code, REST is all about resources and how we deal with their representations. Let’s keep it this way and not try to create a new style.Imagine all the time that would be saved if developers were not wrapping APIs from ground up for every new API. Wrappers are all pretty much the same: they provide authentication (most time it’s OAuth1, 2, token based or Basic Auth), they throw exceptions when the response status is not 2XX, they serialize and deserialize your native data format into JSON or whatever media type the API uses and sometimes they provide pagination support. That’s all, so let’s keep it simple and reuse code. Let’s try not to raise a thousand different exceptions for each different wrapper we use, because all HTTP status codes are standardized and mean the same thing, it doesn’t matter from which API it’s coming.And on the other side, there are all the developers using wrappers and having to read extensive documentations that are just bad copies of the original API documentation. Lets face it, we always end up reading both, the wrapper documentation and the API documentation, so lets make simpler wrappers, cut the work and just read the official documentation. I've seen wrapper documentations that try to teach me how to make a POST request, but I already know HTTP, so if you are only teching me how to pass parameters to your poorly named method, don't bother, I can dump my own data to JSON and put it in the body of a HTTP request.For those of you using Python, <a href="https://github.com/vintasoftware/tapioca-wrapper/">tapioca-wrapper</a> is a project to save you time when writing or using a web API wrapper.

Seriously, we can build better web API clients

Join the Tech Forward newsletter

Related articles

Vinta's Impactful Role in the Open Source Community

Modern Agile: Better people = better company on the long-term

Python API clients with Tapioca