No REST for the wicked
Tags: json, graphql, api, jwt
Published: 2017-10-05 13:25:49

---
title: "No REST for the wicked"
published: true
tags: json,graphql,api,jwt
canonical_url: 
---

This article (also read as _rant_) was heavy inspired by the reading of [this article](https://mmikowski.github.io/the_lie/), which puts in words something that was floating in my mind a lot these years of making services talking between each others, being API, mobile client or whatever.

> Why the fuck are we using _REST~ish_ API everywhere?

![if you dont get this, we cannot talk about music...](https://cdn-images-1.medium.com/max/600/0*xlUf1WFioivefp16.)<figcaption>if you don’t get this, we cannot talk aboutÂ music…</figcaption>

#### The Problem

It seems that nowadays a decent developer MUST know and use REST, but how we are doing it? 
 
It’s pretty much clear to me implementing it or just consume it that there’s a lot wrong.  

Main points are covered by the article cited at the beginning, but I’ll just remark some of&nbsp;them:

#### 1. “RESTful APIs are usually tied to&nbsp;HTTP”

and makes use of it scattering logic around too much: headers, verbs, uris, response codes and body. This makes it difficult to debug and totally unintuitive, leading to random implementations.  

When you want to use a 3rd party RESTxxx API you **have to** read the documentation because you can’t give anything for&nbsp;granted:

- Do I need to provide an header or a token in the query string to authenticate calls?
- How the header is&nbsp;named?
- To create a resource do I use a POST or a&nbsp;PUT?
- and for an&nbsp;update?
- and for an&nbsp;upsert?
- When an error occurs do I check only the status code or also the payload? (how many apis have the “status” field in the payload? I did it myself too, many&nbsp;times)
- And the error&nbsp;message?
- To filter out or query a list of resource which fields do I use in the query&nbsp;string?
- And if I want something that isn’t a plain resource but a mixed collection?

#### 2. “The REST vocabulary isn’t rich&nbsp;enough”

This is harshly true because REST is designed after the concept of _resource_, _CRUD_ operations and linking them. It is a good model to represent linked data and managing it just like you can do on a RDBMS, but API are usually **not only** that.  

Let’s just think of a mobile social app API where within the things you have&nbsp;to:

- register a user  
 -\> _PUT, POST user resource?_
- authenticate a user  
 -\> _is it a resource???_
- create a new blog entry  
 -\> _this I know!!_ _POST /blog yeh!! Done. REST is&nbsp;awesome!_
- like a post  
 -\> _mmm could be_ _POST /blog/666, but I haven’t a payload! Can I use just a GET? and the action does really create a “like” resource or is it just a flag on the blog entry resource? should I use a PUT to update the blog entry resource?&nbsp;…&nbsp;wtf_
- search fora collection of resources  
 -\> _GET /resource yes! search criteria and filters? queryString parameters? body payload? if that i need a POST but I am not creating nothing&nbsp;:( fuck wasn’t SOAP better? hell no! but&nbsp;wtf!_
- ask for a profile of a user but with more or few information  
 -\> _query string parameter? another uri endpoint?_
- make new friend request  
 -\> _ooh&nbsp;fuck!_

![](https://cdn-images-1.medium.com/max/400/0*HlVw0Hly7m8727AV.gif)

It’s a mess and everyone is doing it in a different way, also REST related frameworks roll their own philosophy.

REST was a bless because it gave us freedom from the strictness of SOAP for example, but at what price?  

Confusion I guess.

Whenever we have to design a REST~ish API, we have to answer too much questions and the problem is that **there is no right&nbsp;answer**.

#### Existing solutions

I am obviously not the only one having these feelings so there are people around trying to nail these points, author of the cited article propose his solution [JSON-pure API](https://mmikowski.github.io/json-pure/). I think that it’s not so beautiful and usable, it kind feel going back to a SOAP~ish thing, but it has great&nbsp;ideas:

- be agnostic of the transport, no more significant content attached to protocol specific things, like response code and headers, enable the use of whatever transport we should need: HTTP, Websocket, XMPP&nbsp;…
- JSON is easy to&nbsp;debug

More stable and adopted things are out there: [jsonapi](http://jsonapi.org/), [HAL](http://stateless.co/hal_specification.html), [Mason](https://github.com/JornWildt/Mason), [Collection json](https://github.com/collection-json/spec).  
 I think that each one either is not complete or just addresses the same resource/CRUD model, just in a different way.

What also I think is: we need a sort of _standard_ to do _standard things_.  
 I think that there should be a best practice to do authentication for API, error handling and response format, things that from an API consumer point of view let you integrate more quickly.  

SOAP, bad as it was, let you create clients by themselves that maybe it is too much, but it was intuitive to use, REST~ish things are not.  

No, I don’t want to go back to SOAP&nbsp;:P&nbsp;so…

#### An idea…

The new idea is an old idea.  

I don’t mean to write a new protocol specification.

![xkcd](https://cdn-images-1.medium.com/max/500/0*A-KwNlmdkUdMlKfo.png)<figcaption>xkcd</figcaption>

I think that the right things are already there but have just to be put together.  

So what I want to write is more a “Specification of best practice” or a “Protocol that is just already-known-protocols composition”.

#### What it should be made&nbsp;of?

- Since API are not just CRUD operation but more something like _actions_ or _procedure_ maybe a simple **RPC** is what we need. We already have a nice specification: [JSON-RPC](http://www.jsonrpc.org/specification). It’s clean, simple as json, agnostic from the transport and there’s already a lot of clients libraries.
- Requests authentication, where needed, should be embedded in this protocol and [**JWT**](https://jwt.io/) I thinks is the right fit for that.  
 Also RPC methods regarding authentication should be in the protocol specification standardising the jwt generation.
- We can make a hazardous jump and have [JSON Schema](http://json-schema.org) over the JSON-RPC payload to validate the API format, and with little effort have the API clients library autogenerated from the schema (hello again SOAP&nbsp;:3&nbsp;).

#### Are you sure you need RPC there’s this thing called GraphQL&nbsp;…

It’s been a while since I jot down these thoughts about REST, but never wrapped in an organic discussion, it seems I waited too long. It’s not yesterday that I have stumbled upon [GraphQL](graphql.org), knowing it just superficially, I have seen it just as a wonderful way to retrieve data. A closer look made me totally reconsider RPC. With _Mutations_ you can achieve anything, it is really just like an RPC declaring ahead what you want as a result, beautiful. What you miss from RPC is a uniformed error handling in the response, GraphQL doesn’t enforce anything in this regard. What doesn’t change from RPC is that GraphQL doesn’t deal with authentication too, so you have to take care of that by yourself, who said JWT??.  
 We can embed both in query/mutation, something like:

```
mutation {
  login(username: String!, password: String!) {
    token
    error
  }
}

query {
    myUltraAwesomeApi(token: String, aParameter: String) {
        error,
        result
    }
}
```

#### Conclusions

_It’s time to put REST at rest_, and make API by combine these old/new technologies that are really more appropriate in a many cases. So go out and play with **RPC** , **GraphQL** and&nbsp; **JWT**!

* * *