Ou: como não escrever APIs que fedem

Cléber Zavadniak
May 6, 2017 · 4 min read
Tua API, correndo pelo mato.

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=1 ou 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”.

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

Num sei e num quero sabê!

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 site:

clebertech

Artigos do Cléber sobre tecnologia e trabalho

Cléber Zavadniak

Written by

Cristão reformado, empreendedor, desenvolvedor

clebertech

Artigos do Cléber sobre tecnologia e trabalho

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade