Endpoints raise rigid walls within your data

Relationships allow you to build amazing products and services. Don’t let your API get in the way.

We were quite happy with our REST api at letsevents.com.br, until we needed to render a lot of data on a single request, which was quite painful performance-wise. We were in our way to break down the data requirements by analyzing scenarios and tailoring requests to the essential information. From the webapp perspective, we would define what data was needed for each use-case, so that we could gradually request it in tiny little pieces, on demand.

… but …

Endpoints raise rigid walls within your data.

And we used to need those walls. They helped us reason about the server-client data flow, limit the context of authorization policies, name things. They helped us limit the exact quality that makes our data special: the relationships within.

With a resource-centric api, achieving a granular data retrieval logic often requires multiple requests. You would be happy if you could get away with requests you can paralelize. But the truth is harsh and on most cases they’re quite interdependent. You know, since your data is full of relationships.
So we acknowledged that going granular increased our client complexity, and perceived performance would also suffer.

We realized we had to change focus: to write an API that expands possibilities, allowing clients to name new relationships, extracting information we did not knew we had. The cool thing is, facebook had already thought about this and developed Graphql.

In less then a week we’ve made a proof of concept implementation of a GraphQL api using the amazing ruby gem, and had most of our REST api translated (oops!). We’re talking about implementing roughly the requirements that took our engineering team months do develop.

Adapting our Backbone.js based client to use the new api was easy and straightforward: we just needed to redefine the Backbone.sync behavior and tweak some variables. Nothing major.

But translating is not enough. We’re now rethinking the ways clients interact with our data given the new capabilities brought by GraphQL. In this process we’ve learned a few more things, like how nice to have a self-descriptive api, with an amazing interactive console, and not having to write or maintain so much documentation.
I’ll let you know how that goes any time soon :)

Originally posted on Medium