BT

Livro Design de APIs Web - Criando Interfaces que os Desenvolvedores Adoram

por Bienvenido David III , traduzido por Reinaldo Braga em 20 Abr 2012 |

A empresa Apigee, fornecedora de produtos de API e tecnologia para empresas e desenvolvedores, anunciou o lançamento de seu livro gratuito "Web API Design: Crafting Interfaces that Developers Love", tem como assunto o projeto de APIs Web. O livro é uma coleção de práticas de design de API usando REST, desenvolvido em colaboração com várias equipes construtoras de API ao redor do mundo que participaram da oficina de design da Apigee. O livro, escrito por Brian Mulloy, Vice-Presidente de Produtos da empresa, tem apenas 38 páginas e é de leitura fácil.

Segue um breve resumo do livro. O livro descreve diversas decisões de projeto e compara o modo como algumas das APIs REST mais populares são construídas hoje.

Substantivos. Use substantivos, em vez de verbos em suas URLs de base, e mantenha elas simples usando duas URLs de base por recurso. Use verbos HTTP (GET, POST, PUT e DELETE) para operar em coleções e elementos. Use plurais, em vez de substantivos singulares. Use nomes concretos ao invés de abstratos. Por exemplo, para consultar todos os cães e um cachorro específico.

 

GET /dogs
GET /dogs/1

O livro discute as opções quando o cliente não oferece suporte a todos os diferentes métodos HTTP.

Associações. Simplificar as associações entre recursos e evitar níveis profundos nas URLs. Mova complexidade como parâmetros e atributos após o ponto de interrogação do HTTP. Veja como podemos obter todos os cães pertencentes à um proprietário em particular, e apenas os da cor preta.

 

GET /owners/1/dogs
GET /owners/1/dogs?color=black

Erros. Use os códigos de status do HTTP. Os mais usuais são HTTP 200, 400,401, 403, 404, e 500. Retorne mensagens detalhadas e claras no corpo da resposta. Aqui está um exemplo de resposta JSON. Observe o uso de URLs para mais informações.

{
      "developerMessage" : "...",
      "userMessage" : "...",
      "errorCode" : 100,
      "moreInfo": "http://developers.company.com/errors/100"
}

O livro discute as opções quando o cliente sempre espera um HTTP 200, como algumas versões do Adobe Flash.

Versões. Fazer controle de versão de sua API é obrigatório. Especifique a versão utilizando o prefixo 'v' no primeiro nível. Use um número com um dígito, para enfatizar que é para o controle da interface e não da implementação. Aqui está um exemplo de como obter todos os cães utilizando a versão 1 do sua API.

GET /v1/dogs

Respostas parciais e paginação. Use uma lista separada por vírgulas para especificar quais campos você quer na resposta. Use o "limit" (qtde de itens na resposta) e "offset" (índice do primeiro item a ser retornado) para paginar os recursos. Estes parâmetros são comuns e já utilizados em bancos de dados. Veja como obter cães com apenas os atributos cor e raça e outro exemplo buscando os primeiros 10 cães.

GET /dogs?fields=color,breed
GET /dogs?limit=10&offset=0

Verbos. Se a sua API devolve uma resposta que não é um recurso, então faz mais sentido usar verbos ao invés de substantivos. Deixe claro na documentação da API que estes "não-recursos" são diferentes do restante da API. Aqui está uma chamada para a conversão de 100 Euros para os Yen chineses.

/convert?from=EUR&to=CNY&amount=100

Tipos de conteúdo. É recomendado que as APIs suportem diversos formatos de resposta como JSON e XML. Para especificar o formato de retorno, use a notação de "ponto tipo", como uma extensão de nome de arquivo (por exemplo ".json"). Deixe o formato JSON como padrão, como é menos verboso e pode ser facilmente consumido usando JavaScript. Veja como obter todos os cães em XML.

GET /dogs/1.xml

Atributos. Siga as convenções do JavaScript para nomear atributos. Use "CamelCase", colocando a primeira letra maiúscula ou minúscula dependendo do tipo de objeto. Aqui está um exemplo de um atributo ID do usuário.

{
    "userId": 1
}

Bucas. Para fazer uma busca através de vários recursos, use o verbo "search" (ou "pesquisa", caso sua API esteja traduzida) e o parâmetro de consulta "q" (imitando o Google). Especifique o formato usando notação de "ponto tipo". Aqui está um exemplo de busca por todos os recursos usando "fluffy", nos formatos padrão e XML.

GET /search?q=fluffy
GET /search.xml?q=fluffy

Para adicionar escopo à sua pesquisa, você pode usar uma URL base juntamente com o parâmetro de consulta. Por exemplo, aqui está uma busca por todos os cães, pertencentes a um proprietário particular, que são macios (fluffy).

GET /owners/1/dogs?q=fluffy

Subdomínios. Consolidar todas as solicitações para a API sob um subdomínio. Use algo como "api.empresa.com.br". Criar um portal dedicado aos desenvolvedores, como "desenvolvedores.empresa.com.br", é uma boa idéia. Você também pode querer redirecionar os usuários que acessam o subdomínio da API utilizando um navegador para o portal do desenvolvedor.

Autenticação. Use o padrão OAuth 2.0. Ele permite o acesso as API sem compartilhamento de senhas. Também permite que os fornecedores da API revoguem os tokens de acesso e ainda permite aos desenvolvedores usarem as mesmas bibliotecas OAuth usadas para outras APIs.

APIs Verbosas. Algumas APIs podem tornar-se muito "verbosas". Isso significa que é preciso muitas chamadas para o servidor afim de construir uma aplicação simples. A recomendação é criar uma API completa e RESTful e criar atalhos ou respostas compostas, se necessário.

SDK. É recomendável que os fornecedores de API complementem a mesma com exemplos de código, bibliotecas e kits de desenvolvimento de software. Essas ações promovem a rápida adoção em plataformas específicas. Ainda ajuda a reduzir código ruim ou ineficiente, que pode desacelerar o serviço. O kit ajuda a vender a API para diferentes comunidades de desenvolvedores.

Fachada da API. Existem várias maneiras de arquitetar a sua API. A abordagem recomendada é chamada de "Padrão Fachada de API" (Pattern Facade API), que envolve três etapas básicas.

  • Projete a API ideal. Faça o design das URLs, parâmetros, respostas, formatos, cabeçalhos, e assim por diante.
  • Implemente com stubs (dublês). Isto permite aos desenvolvedores usarem a API e dar feedback, mesmo antes da API estar ligada aos sistemas internos.
  • Integre a fachada com os sistemas internos.

O objetivo é certificar-se que a sua API seja intuitiva e fácil de usar para os desenvolvedores de aplicativos.

Para maiores detalhes, leiam o livro completo baixando o Web API Design Book no site Apigee. Para comentários e sugestões, visite o grupo de discussões API do Google Craft (em inglês).

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

Formato na extensão? by Daniel Serodio

Porque usar a extensão pra especificar o formato desejado se o cabeçalho Accept existe pra isso?

Re: Formato na extensão? by Joel Lobo

Daniel, concordo com você. Eu e o Mark Masse :) Vide shop.oreilly.com/product/0636920021575.do No livro ele diz:
"Rule: file extensions should not be included in URIs
REST API clients should be encouraged to utilize HTTP's provided format selection mechanism, the Accept request header, as discussed in the section Rule: Media type negotiation should be supported when multiple representations are available."

@joellobo
blogdojoellobo.blogspot.com

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

2 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