Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. Node.js

Projeto de APIs RESTful com NodeJS e Restify

by
Difficulty:IntermediateLength:LongLanguages:

Portuguese (Português) translation by Erick Patrick (you can also view the original English article)

Final product image
What You'll Be Creating

Uma API RESTful consiste de dois conceitos principais: Recurso e Representação. Um Recurso pode ser qualquer objeto associado a um dado ou identificado a uma URI (mais de uma URI pode referir-se a um mesmo recurso), e que pode ser operado usando métodos HTTP. Uma Representação é uma forma de apresentar um recurso. Neste tutorial, passaremos um conteúdo teórico sobre projetos de APIs RESTful e implementaremos uma API de blog, usando o NodeJS.

Recurso

Escolher os recursos corretos para uma API RESTful é uma parte importante do projeto. Primeiro de tudo, você precisa analisar o domínio do seu negócio e, depois, decidir quantos e quais recursos serão usados e que são relevantes às necessidades do seu negócio. Se você estiver projetando uma API para um blog, provavelmente usará recursos como Artigo, Usuário e Comentário. Esses são os nomes dos recursos e os dados associados a eles são o recurso em si:

Verbos de Recursos

Podemos prosseguir com a operação do recurso após decidir quais são os recursos obrigatório. Operações referem-se aos métodos HTTP. Por exemplo, para criarmos um artigo, podemos realizar a seguinte requisição:

Da mesma forma, podemos visualizar um artigo realizando a seguinte requisição:

E quanto a atualizar um artigo já existente? Sei muito bem o que você está pensando:

Posso realizar outra requisição POST em relação a /articles/update/123456789012 com os dados a serem atualizados.

Talvez, mas a URI está ficando um pouco mais complexa. Como disse mais cedo, as operações referem-se aos métodos HTTP. Isso significa que devemos apresentar a operação de atualização no método HTTP ao invés de colocá-lo na URI. Por exemplo:

Por falar em alterações, neste exemplo podemos ver campos de tags e categorias. Eles não são campos obrigatórios. Você pode deixá-los em branco e preenchê-los no futuro. 

Algumas vezes, você precisa remover um artigo que esteja desatualizado. Nestes casos, você pode usar uma requisição HTTP do tipo DELETE em relação à URI /articles/123456789012.

Os métodos HTTP são conceitos padrões. Se usá-los como operações, você terá URIs mais simples e esse tipo de API simples ajudará você a obter clientes, clientes felizes.

E se você quisesse publicar um comentário em um artigo? Você pode selecionar o artigo e adicionar um comentário novo a ele. Com essa expressão em mente, você pode realizar a seguinte requisição:

A forma de recurso acima é chamada de sub-recurso. Comentário é um sub-recurso de Artigo. Os Comentário e sua carga acima serão inseridos na base de dados como um filho de Artigo. Algumas vezes, uma URI diferente refere-se a uma mesmo recurso. Por exemplo, para ver um comentário específico, você pode usar tanto:

ou:

Versionamento

Geralmente, funcionalidades de uma API alteram-se frequentemente, para que se possa oferecer novas funcionalidades aos clientes. Neste caso, duas versões de uma mesma API podem existir ao mesmo tempo. Para separá-las, você pode usar versionamento. Há duas formas de versionamento

  1. Versão na URI: Você pode prover o número de versão na própria URI. Por exemplo, /v1.1/articles/123456789012.
  2. Versão no Cabeçalho: Você pode prover o número da versão no cabeçalho e nunca precisar mudar a URI. Por exemplo:

Na verdade, a versão apenas altera a representação do recurso, não o conceito do recurso em si. Então, você não precisa alterar a estrutura do URI. Na v1.1, talvez um novo campo seja adicionado ao Artigo. Entretanto, ele ainda retorna um artigo. Na segunda opção, a URI continua simples e os clientes não precisam alterar as URIs em suas implementações. 

É importante projetar uma estratégia para situações onde o cliente não provê um número de versão. Você pode lançar um erro quando um número de versão não é apresentado ou você pode retornar uma resposta usando a primeira versão. Se você usar a última versão estável como a versão padrão, os clientes podem obter vários erros em suas implementações.

Representação

A Representação é a forma como uma API apresenta um recurso. Ao invocar uma API através de uma URI, você receberá um recurso. Esse recurso pode estar em um formato como o XML, JSON, etc. É preferido o formato JSON caso esteja projetando uma nova API. Entretanto, se você estiver atualizando uma API já existente e que já é acostumada a retornar uma resposta XML, você pode prover outra versão com uma resposta em JSON. 

Certo, deixemos a teoria sobre projetos de APIs RESTful de lado. Vejamos como projetar e implementar uma API para blogs usando o Restify.

API RESTful de um Blog

Projeto

Para projetarmos uma API RESTful, precisamos analisar o domínio do negócio. Só então podemos definir nossos recursos. Em uma API de blogs, precisamos:

  • Criar, Atualizar, Apagar e Visualizar um Artigo
  • Criar comentários para um Artigo específico, além de Atualizar, Apagar e Visualizar um Comentário
  • Criar, Atualizar, Apagar e Visualizar um Usuário

Nesta API, não cobrirei a parte de autenticação necessária para criar um artigo ou comentário. Para essa parte, você pode referir-se ao artigo Autenticação com Tokens Usando AngularJS & NodeJS

Os nomes dos nossos recursos estão prontos. Operações de recursos são CRUD simples. Você pode referir-se à tabela a seguir para ter uma visualização geral da API.

Nome do Recurso Verbos HTTP Métodos HTTP
Artigo criar Artigo, atualizar Artigo, remover Artigo, visualizar Artigo POST /articles com os dados, PUT /articles/123 com os dados, DELETE /articles/123 e GET /article/123
Comentário criar Comentário, atualizar Comentário, remover Comentário, visualizar Comentário POST /articles/123/comments com os dados, PUT /comments/123 com os dados, DELETE /comments/123 e GET /comments/123
Usuário criar Usuário, atualizar Usuário, remover Usuário, visualizar Usuário POST /users com os dados, PUT /users/123 com os dados, DELETE /users/123 e GET /users/123

Configuração do Projeto

Neste projeto, usaremos o NodeJS com Restify. Os recursos serão salvos em uma base de dados MongoDB. Antes de tudo, devemos definir os recursos como modelos no Restify.

Artigo

Comentários

Usuário

Não haverá operações para o recurso Usuário. Assumiremos que já sabemos o usuário atual que será capaz de operar os artigos ou comentários.

Você deve se perguntar de onde esse módulo mongoose vem. É o framework ORM para MongoDB escrito como módulo para NodeJS mais conhecido. Este módulo está incluso no projeto, dentro de outro arquivo de configuração. 

Agora, podemos definir nossos verbos HTTP para os recursos acima. Você pode ver abaixo:

Neste trecho de código, a primeira coisa feita é iterar sobre todos os arquivos dos controladores e inicializá-los, para que uma requisição específica possa ser realizada. Após isso, URIs para operações específicas são definidas em relação às operações CRUD básicas. Também há versionamento para uma das operações em relação ao recurso Artigo

Por exemplo, se você configurar a versão como sendo a 2 no cabeçalho Accept-Version, o método viewArtigo_v2 será executado. viewArtigo e viewArtigo_v2 realizam o mesmo trabalho, apresentando o recurso, mas mostram o recurso Artigo em formatos diferentes, como pode ser visto através do campo title, no exemplo abaixo. Finalmente, o servidor é iniciado numa porta específica, além da aplicação de alguns relatórios de erros. Podemos dar continuidade com os métodos dos controladores mapeados às operações HTTP em relação aos recursos.

article.js

Uma explicação básica das operações CRUD em relação ao Mongoose pode ser visto logo abaixo:

  • createArtigo: A operação save simplesmente salva os dados recebidos no corpo da requisição, usando o modelo articleModel. Um novo objeto Artigo pode ser criado, enviando os dados do corpo da requisição para o modelo em questão, dessa forma var articleModel = new Artigo(req.body)
  • viewArtigo: Para vermos os detalhes do artigo, é preciso que tenhamos o ID de um artigo como parâmetro na URL. O método findOne usando o ID do parâmetro é mais que o suficiente para retornar os detalhes do artigo.
  • updateArtigo: A atualização de um Artigo é uma simples consulta e manipulação de dados em relação ao artigo retornado. Por fim, o artigo atualizado precisa ser salvo na base de dados, através do comando save.
  • deleteArtigo: O método findByIdAndRemove é a melhor forma de removermos um artigo a partir do ID de um artigo.

Os comandos do Mongoose mencionados acima são quase como métodos estáticos do objeto Artigo, o qual é uma referência a um esquema do Mongoose.

comment.js

Ao realizar uma requisição a uma das URIs, a função declarada no controlador será executada. Cada função dentro dos arquivos de controladores pode usar os objetos req e res. O recurso comentário logo acima, é um sub-recurso de Artigo. Todas as operações de consultas são realizadas através do modelo Artigo para, então, encontrarmos o subdocumento e realizar as atualizações necessárias. Contudo, toda vez que tentamos visualizar um recurso do tipo Comentário, você verá algo, mesmo que não exista uma coleção no MongoDB.  

Outras Sugestões de Design

  • Escolha recursos simples de entender para prover uso fácil aos clientes;
  • Não deixe a lógica do negócio ser implementada pelos clientes. Por exemplo, o recurso Artigo tem um campo chamado slug. Os clientes não precisam enviar esse detalhe pela API RESTful. A estratégia em relação ao slug deve ser administrada no lado da API RESTful para minimizar o acoplamento entre a API e os clientes. Os clientes só precisam enviar o título e você pode gerar o slug de acordo com as necessidades do negócio, no lado da API RESTful.
  • Implemente uma camada de autorização para suas APIs. Clientes não autorizados não podem acessar dados restritos pertencentes a outros usuários. Neste tutorial, não falamos sobre o recurso Usuário, mas você pode ler o artigo Autenticação com Tokens Usando AngularJS & NodeJS para mais informações em relação a autenticação de APIs.
  • URIs amigáveis ao invés de vetor de consulta. /articles/123 é bom, /articles?id=123 é ruim.
  • Não mantenha estados; sempre use entrada/saída instantâneas.
  • Use substantivos para seus recursos. Você poderá usar os métodos/verbos HTTP para operar sobre os recursos.

Finalmente, se você projetar uma API RESTful seguindo essas regras fundamentais, você sempre terá um sistema flexível, manutenível e compreensível.

Seja o primeiro a saber sobre novas traduções–siga @tutsplus_pt no Twitter!

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.