O Guia Definitivo para construção de APIs REST
Ou: como não escrever APIs que fedem
Your API stinks!
— Me
O “I” de “API” é de “Interface”, e me parece que “o mal do século” no mundo da programação é a falta de boas interfaces. Nós temos bom hardware, boas linguagens de programação, boa velocidade de rede para comunicar processos inter-máquinas (inter-continentalmente, inclusive) e temos bons protocolos à nossa disposição. Mas o desenho de interfaces parece avançar como “a lesma subindo o poço” dos problemas de Física do Ensino Médio: sobe um metro e meio, desce um metro, sobre um metro e meio, desce um metro…
Enquanto os protocolos cumprem o papel de linguagem (e uma espécie de meio, especialmente nos níveis “físicos” dos protocolos de rede, por exemplo), definindo como um componente deve “falar” com o outro (desculpa, São Dijkstra, eu antropomor… fi… zo… descaradamente, mesmo), as interfaces definem o que um componente deve dizer ao outro e o que esperar como resposta.
Ora, na vida real há uma porção de exemplos em que devemos escolher uma “interface” adequada para nossa comunicação. Um processo de bug reporting, por exemplo, dentro de uma equipe de desenvolvimento, pode ser tão ruim quanto isso:
Cara, tá dando pau nos arquivos…
Ou tão bom quanto:
Ao tentar baixar um arquivo, encontrei esse problema: ao invés de receber status_code 302 com “Location” adequado, está vindo erro 401. Veja:
$ http GET “http://localhost:8000/v1/files/42?_download=1" “Authorization: token $TOKEN”HTTP/1.1 401 Unauthorized
Connection: keep-alive
Content-Type: text/html; charset=utf-8
Date: Fri, 05 May 2017 21:57:37 GMT
Server: gunicorn/19.6.0
Transfer-Encoding: chunked
Vary: Cookie
Via: 1.1 vegur
X-Frame-Options: SAMEORIGIN
O token que estou utilizando é válido. Acabei de checar.
Se eu acesso o endpoint sem o
_download=1ou com_download=0, tudo funciona como deveria (status_code 200).
Perceba que o protocolo em ambos os casos está correto: o idioma português. O meio pode estar correto, também: pode ser uma Issue no Github ou no bug tracker da escolha do time. Mas a interface no primeiro exemplo, é horrível, pois ela é o gatilho para “a dança do bug report ruim”, cujo segundo passo é “que tipo de problema você está tendo?”. Por isso as equipes de desenvolvimento escolhem mais do que um protocolo (o idioma português?) ou um meio (Bugs no Jira?), mas também o jeito certo de se reportar um bug: isso é uma espécie de interface. Se é definido que o bug report deve ser como no segundo exemplo, um report como o do primeiro será rejeitado por não atender uma série de critérios pré-estabelecidos.
Com isso em mente, vamos falar sobre as interfaces entre programas de computador, as APIs.
Por que APIs fedem
1- Porque são “quase” REST. Ênfase no “quase”.
Usar HTTP e responder com JSON (e/ou XML) não faz da sua API uma API REST. O cúmulo maior da bizarrice em comunicações da história da computação, o SOAP, usa (/pode usar) HTTP e serializa dados com XML, mas… né?, não por isso chamamos SOAP de REST.
O problema aqui é cair no meio-termo: você poderia estar utilizando um padrão simples reconhecido universalmente ou usar qualquer outro padrão, mas não: o seu jeito tupiniquim acaba caindo no “quase”: é bem parecido com REST — mas não é REST. E, não tendo sequer um nome, você simplesmente não fala nada a respeito na documentação da API.
Ou, o que é ainda pior: você diz que é REST, mas, na verdade, não é.
1.1- Ignorância sobre o HTTP
Muitas vezes, essas APIs quase-REST são resultado de uma tentativa legítima mas frustrada de sê-lo. E o motivo de não conseguir fazer isso direito, pelo que entendo, reside na não-confiança no protocolo HTTP. O que, em geral, é meramente por ignorância a respeito do mesmo.
Minha sugestão: leia a RFC:
(Caso você já tenha alguma familiaridade com as RFCs, repare que a 7230 torna a 2616 obsoleta. E há, sim, algumas diferenças bem importantes entre elas. ;-)
Leia o restante lá no meu novo site:
https://blog.cleber.solutions/software/o-guia-definitivo-para-construcao-de-apis-rest
