Não divulgue sua API como sendo RESTful. Esse é um dos conselhos dados pelos desenvolvedores de APIs em mais um episódio do Nodeup Podcast: uma API revela. O podcast traz uma conversa entre Daniel Shaw, engenheiro na Voxer e anfitrião da Nodeup, James Halliday, fundador do Browserling e os convidados Mark Cavage e Andrew Sliwinksi. Cavage é engenheiro de software no provedor de infraestrutura de cloud Joyent e também autor do pacote para Node.js, Restify. A Joyent desenvolve Node.js e o utiliza extensivamente. Sliwinski é cofundador e CTO do website DIY.
A conversa abordou as principais preocupações no desenvolvimento de APIs com Node.js, incluindo os valores do REST, segurança, testes, documentação, esquemas e transmissão. Segundo eles, o método preferido para projetar uma API é "começar com um documento README". Deve-se abordar o projeto da API como se estivesse construindo uma interface de usuário. Cavage explicou sobre como a Amazon.com aborda o desenvolvimento de produtos "escrevendo primeiro o comunicado a impresa". Ele ainda cita a criação de uma API mínima inicial e o desenvolvimento dela através da experiência de uso. Não tente incluir muitas funcionalidades de uma vez.
O valor do REST é considerado misto. O problema de anunciar sua API como RESTful é o fato de isso poder soar negativamente, de acordo com Shaw. As pessoas são receosas sobre a performance do REST. Mais importante, são receosas sobre o HTTP que é o protocolo abaixo do REST. Cavage diz que o protocolo HTTP é "a interface que você deseja utilizar por causa dos firewalls", mas internamente você pode converter para qualquer formato de dados e transporte mais eficiente que faça sentido, ressaltando que "o HTTP vem com um custo". Ele cita o dnode e o fast como exemplos de frameworks RPC que a Joyent utiliza em suas infraestruturas de backend.
O tópico sobre segurança de APIs gerou alguns debates durante a conversa. Halliday e Shaw acham que novos protocolos de segurança como o OAuth se tornaram um empecilho para o consumo de APIs através de linha de comando, utilizando ferramentas como Curl. Entretanto Cavage contraria que a segurança deve estar alinhada com o valor da API que se deve proteger e que a autenticação básica do HTTP nem sempre é suficiente. Cavarage apresentou o HTTP Signatures, que em sua opinião, é uma opção melhor em relação a utilização de password porém "mais fácil que outros protocolos". O HTTP Signatures adiciona características como autenticação de origem, integridade de mensagem e replay resistance às requisições HTTP. Desenvolvido na Joyent, o HTTP Signatures foi recentemente submetido ao IETF.
Todos concordaram que os testes devem ser baseados em sistemas e dados reais e que o hábito de criar "mocks" é uma má prática. O problema com o mocking é tornar o teste desconexo com a realidade, explica Halliday. Sliwinski explica que na DIY, um banco de dados local é populado com dados reais para aplicar testes de integração continua sem recorrer aos mocks. Algumas das ferramentas utilizadas incluem Nodeunit, Tap e Travis CI.
No tópico sobre documentação, na DIY, a documentação da API é feita primeiramente em um formato de especificação JSON resultando em uma página de documentação interativa. Cavage descreve como é utilizado o Restdown na Joyent para documentar APIs e manter a documentação em um repositório onde a API é hospedada. Manter a documentação atualizada com a API é um desafio importante e todos concordam que é preferível ter uma documentação interativa com dados de exemplos.
Esquemas são outra área problemática. Dois problemas com validadores de esquema se concentram na lentidão e erros obscuros, explica Cavage. Mas por outro lado, fazer as coisas utilizando as próprias mãos e sem uma gramática formal é arriscado. A DIY utiliza o JSONSchema porém ele vem com algumas desvantagens. O padrão ainda está em evolução e não há implementações de validores JSON Schema para Node.js. Sliwinski disse ter algumas boas experiências com o JSV porém tiveram que encapsular e reinterpretar as mensagens de erro obscuras.
O podcast inclui muitas discussões sobre APIs de trasmissão que tiram vantagem da arquitetura não-bloqueante de I/O do Node.js. Halliday explica que transmitir JSON em APIs faz muito sentido para evitar buffering e latência. Cavage aponta que o suporte à transmissão de JSON é uma das principais razões para a utilização do Restify como alternativa ao pacote Express.
Mas voltando a pergunta levantada no começo do artigo. É seguro anunciar sua API como RESTful, ou isso encoraja más práticas das pessoas receosas? O REST seria um padrão a ser seguido ou um conjunto de restrições? Onde desenhar a linha que divide o que é RESTful ou não? Gostaríamos de ouvir sua experiência.