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.

Avalie esse artigo

Relevância
Estilo/Redação

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 mensagens dessa discussão
Comentários da comunidade

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

Receber mensagens dessa discussão

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

Receber mensagens dessa discussão

Dê sua opinião
Feedback geral
Bugs
Publicidade
Editorial
Marketing
InfoQ Brasil e todo o seu conteúdo: todos os direitos reservados. © 2006-2016 C4Media Inc.
Política de privacidade
BT

We notice you’re using an ad blocker

We understand why you use ad blockers. However to keep InfoQ free we need your support. InfoQ will not provide your data to third parties without individual opt-in consent. We only work with advertisers relevant to our readers. Please consider whitelisting us.