BT

O que deve e o que não deve ser feito em uma API Web

por Jan Stenberg , traduzido por Gabriel Ozeas em 29 Nov 2013 |

Há uma série de discussões em torno do REST e das APIs web nas listas e fóruns de discussão, e na opinião de Oliver Wolf, consultor sênior na InnoQ, não há uma verdade absoluta. Foi assim que Wolf iniciou a sua palestra "O que deve e o que não deve ser feito em uma API Web", na conferência GOTO Berlin.

Não pense em termos de endpoints. A especificação SOAP possui uma fachada com um ponto de entrada único. Em contraste com a web, que possui vários pontos de entrada que são construídos a partir de relacionamentos e interconexões, tendo a hipermídia como um elemento crítico. Em vez de fazer com que a sua API se torne um buraco negro com apenas uma via de entrada, deve-se utilizar controles de hipermídia para vincular as suas representações de recursos, de modo que tenham significado para o seu público.

Não exponha o seu modelo de domínio em sua API. Um problema presente em vários modelos é que estes contêm somente dados, sendo carentes de todos os tipos de comportamento (chamados de modelos anêmicos). A exposição de um modelo como este acaba gerando recursos CRUD (Create, Read, Update, Delete). Isto não é necessariamente um ponto negativo, pois às vezes tudo o que se precisa é de uma API CRUD pura. Entretanto, um problema em se expor somente um modelo CRUD é que um cliente usando uma API precisa de muito conhecimento: quais ações podem ser executadas em quais recursos; em qual ordem fazer as coisas etc. Muita lógica está presente no cliente, gerando um acoplamento forte entre o cliente e o servidor.

Projete sua API além da intenção. Pense sobre o que o seu cliente quer e o que fará. Ocasionalmente isto requer um equilíbrio entre clareza e flexibilidade, o quão limpa e simples a sua API deve ser versus qual flexibilidade é necessária. Um modo flexível, porém mais imperativo de consultar quais são os clientes mais rentáveis, poderia ser assim:

GET /customers?sortBy=grossmargin&order=descending

Em contrapartida, um estilo mais declarativo que expõe a intenção, porém menos flexível, poderia ser assim:

GET /most_profitable_customers

A ideia central de Oliver aqui é pensar sobre o que um cliente precisa para usar a sua API, qual seria o seu objetivo e tentar adatá-la para este fim.

Não abuse dos verbos GET e POST. Basicamente significa que não se deve utilizá-los da forma errada e que violem a especificação HTTP. Deve-se, por exemplo, não utilizar os verbos GET e POST para deletar um recurso. Os verbos HTTP são definidos por uma razão, eles possuem qualidades complementares e ganha-se muito ao seguir a especificação. Utilizar os verbos transmite intenção, o que o cliente espera fazer e qual o comportamento o cliente pode esperar do servidor.

Não limite as suas opções de códigos de erro em 200 e 500. Utilize todo o espectro de códigos de erro, há 160 códigos de erro para se escolher e há um para quase todos os tipos de erro concebíveis. Utilizar o código de erro correto é chave para o tratamento adequado do erro no cliente.

Um problema comum é os servidores retornarem 200 (OK), embora tenha ocorrido um erro. Fingir que está tudo bem quando na verdade não está, nem sempre é uma boa ideia.

Não ignore o cache. Haverá caches envolvidos, sejam quais forem, e estes são uma parte muito importante da web. Auxilie os caches adicionando cabeçalhos de cache apropriados. Se, por exemplo, não quiser que o cache seja realizado, seja explicito e o desligue.

Uma das melhores formas de se controlar o caching é utilizar validadores, de preferência Etags, que permitem ao lado do servidor agir sobre dados arbitrários. Uma ETag é apenas um valor que o servidor gera e passa para o cache, e é posteriormente devolvido ao servidor pelo cache, que questiona o servidor sobre a recentidade do recurso.

Não obrigue versionamento. O que é considerado como uma alteração de um recurso, na maioria das vezes é de fato uma alteração na representação. O recurso continua sendo o mesmo e mantém a mesma URL, sendo assim evite versionar a URL. Em vez disso deve haver uma nova versão do tipo de media, adicionando-se v2, por exemplo:

Content-Type=application/vnd.company.v2+xml

Não utilize extensões na negociação de conteúdo. A forma adequada de se negociar sobre um formato de representação é através do uso do Accept e Content-Type no cabeçalho.

A GOTO Berling Conference 2013 foi a primeira conferência GOTO em Berlin, e reuniu 420 participantes e 80 palestrantes.

Olá visitante

Você precisa cadastrar-se no InfoQ Brasil ou para enviar comentários. Há muitas vantagens em se cadastrar.

Obtenha o máximo da experiência do InfoQ Brasil.

Dê sua opinião

HTML é permitido: a,b,br,blockquote,i,li,pre,u,ul,p

Receber menssagens dessa discussão
Comentários da comunidade

HTML é permitido: a,b,br,blockquote,i,li,pre,u,ul,p

Receber menssagens dessa discussão

HTML é permitido: a,b,br,blockquote,i,li,pre,u,ul,p

Receber menssagens dessa discussão

Dê sua opinião

Conteúdo educacional

Feedback geral
Bugs
Publicidade
Editorial
InfoQ Brasil e todo o seu conteúdo: todos os direitos reservados. © 2006-2014 C4Media Inc.
Política de privacidade
BT