Darter-Bird

Darter: RESTful APIs em Dart

Lembram da última publicação que escrevi falando sobre as ferramentas disponíveis em Dart para criar APIs RESTful? Eu reclamei de algumas características que essas ferramentas não tinham, certo? E como resolver isso? Uma forma seria contribuir para o Redstone, por exemplo. Só que, infelizmente, não dá para modificar o Redstone para permitir o controle de versionamento de APIs, conforme você pode ver nessa issue que abri lá. Outra forma seria trabalhar em cima do RPC da Google. Só que nesse eu não abri issues e nada. hehe. Resolvi logo partir para a violência: criar uma biblioteca própria, considerando não cometer as mesmas falhas que encontrei nessas duas.

O meu guia de referência para essa biblioteca foi o Grape, para Ruby. Em minha opinião, é o framework, para desenvolver APIs RESTful, mais completo e simples de ser usado, independente de linguagem. Uso ele para todas as minhas APIs. Entretanto, é óbvio que não pude criar uma DSL em Dart, já que essa linguagem não dá facilidades para fazer isso da mesma forma como Ruby. Precisei usar a maneira Dart de codificar. Acho que o resultado ficou bom!

Darter

Apresento-lhes o Darter! Meu primeiro projeto open-source para Dart. Ele está servindo para muitos propósitos: estou aprendendo a fundo a linguagem, estou me divertindo pacas e estou contribuindo! O Darter ainda não está em versão final. Precisa de melhorias e correções. Como ainda estou na fase de codificação para provar meu conceito, ainda não escrevi os testes. E, por favor, deixa de #mimimi se isso é certo ou errado, preferi primeiro validar minha ideia para depois partir para tornar a ferramenta mais madura, com testes, exemplos e etc.

Mas, já é possível usá-lo? É sim, companheiro. O Darter já está no Github mas ainda não publicado no Pub. Inclusive, estou escrevendo todo um projeto em cima dele e que também está no Github aqui. Trata-se do meu “projeto-prova-de-conceito”. Ele está totalmente funcional! Agora, vamos ver como funciona o Darter?

 

Exemplo de Uso

O primeiro passo é criar uma classe e anotá-la com @API, assim como fizemos no exemplo abaixo. Observe que esta anotação precisa do argumento path. No caso abaixo, teremos uma rota da seguinte forma: http://localhost/categories.

import 'package:darter/darter.dart';
@API(path: 'categories') 
class MyDarterAPI { }

Depois disso, você já pode iniciar a criação de seus métodos que irão tratar as diversas requisições. Para isso, precisamos usar as anotações @GET@POST@PUT@DELETE e @PATCH. Vamos incrementar a classe acima para refletir isso!

import 'package:darter/darter.dart';

@API(path: 'categories')
class MyDarterAPI {

    @GET()
    List<MyModel> list() {
    }

    @GET(path: ':id')
    MyModel get(Map pathParams) {
    }

    @PUT(path: ':id')
    MyModel put(PathParams params, MyModel myModel) {
    }

    @POST()
    MyModel post(MyModel myModel) {
    }

    @DELETE(path: 'id')
    void delete(Map pathParams) {
    }
}

Observe que omiti o corpo dos métodos, pois meu objetivo é só exemplificar o Darter. Como era de se esperar, com essa classe aí, teremos as rotas:

  • GET http://localhost/categories
  • POST http://localhost/categories
  • PUT http://localhost/categories/<id>
  • GET http://localhost/categories/<id>
  • DELETE http://localhost/categories/<id>

Parâmetros

No exemplo que vimos na seção anterior, note que recebemos como parâmetro um objeto MyModel em alguns casos, enquanto em outros, recebemos um Map. No primeiro caso, o Darter tenta transformar os parâmetros encontrados em uma classe de negócio da sua aplicação. Por exemplo, suponha que você envia uma String JSON para o Darter e seu método tem como parâmetro um objeto de negócio. O Darter vai criar esse objeto e preencher seus atributos com os valores obtidos do JSON.

Mas, é claro, isso não abrange todos os cenários, certo? Claro que não. Existem os Path parameters e Query parameters. E como ter acesso a eles? Através de uma convenção bem simples: crie um parâmetro do tipo Map e dê o nome de pathParams ou queryParams. Você pode me perguntar porque não fiz igual ao JAX-RS (Java), que tem anotações @PathParam e @QueryParam. Simplesmente porque eu acho essa solução feia, medonha. Polui seu código.

Em minha humilde opinião, é muito mais simples e clean você receber um Map contendo os dados. Rápido, caceteiro, simples e eficiente.

Versionamento

Opa! Você não reclamou tanto de versionamento nas outras ferramentas? Sim! E fiz isso de forma mais flexível no Darter! Vamos melhorar a classe anterior (vou omitir agora os métodos só para exemplificar o versionamento).

@API(path: 'categories')
@Version(version: 'v1', vendor: 'company', format: Format.JSON, using: Using.HEADER)
class MyDarterAPI { }

O Darter permite usar dois tipos de estratégias de versionamento: por path e por header. No caso do header, exemplificado acima, você precisa usar a anotação @Version e informar quatro argumentos obrigatórios. Por que? Porque o Darter vai procurar por isso no cabeçalho Accept. Como? Ele espera que esteja no formato application/vnd.<vendor>.<version>+<format>. Entendeu agora o motivo dos argumentos extra? No caso acima, ele espera o cabeçalho formatado assim application/vnd.company.v1+json.

E caso você queira o versionamento no path? Eu não aconselho essa estratégia, mas ela existe e eu não poderia deixar ela de fora. Neste caso, basta modificar a anotação e esquecer os parâmetros extras.

@API(path: 'categories')
@Version(version: 'v1', using: Using.PATH)
class MyDarterAPI { }

Nesta estratégia, você terá a URL http://localhost/v1/categories.

Error Handlers

Suponha que seu método recebe um ID e você vai buscar esse ID na base de dados. Seu mecanismo de busca não encontra e lança uma exceção chamada ObjectNotFoundException. O que sua API deve fazer com essa exceção? O correto é pegar essa exceção e retornar na API um status 404 e uma mensagem de erro! O Darter facilita isso? Claro!

@API(path: 'categories')
@Version(version: 'v1', using: Using.PATH)
class MyDarterAPI { 
    
    @ErrorHandler
    Response handleObjectNotFound(ObjectNotFoundException ex) {
    }

}

A partir deste método, você pode retornar um objeto Response ou qualquer outro objeto, inclusive seus models. Observe que o parâmetro do método deve ser exatamente o tipo da exceção que você quer tratar. E caso você tenha mais de um handler com o mesmo parâmetro? O Darter pega o primeiro e ignora os outros, então, tome cuidado.

Interceptors

Agora, imagine outra situação: você precisa validar antes se o usuário tem permissão de acesso à sua API! Como fazer isso? Com interceptors, meu caro. Um interceptor, como o próprio nome já diz, intercepta uma requisição para que você possa tratar ela. Essa interceptação pode ocorrer antes ou depois que seu método seja chamado. Ah! E você também pode definir a ordem de execução dos interceptors! Vamos deixar de blá blá blá e ver um exemplo?

@Interceptor(when:Interceptor.BEFORE, priority: 1)
class Authentication {

    void intercept(Chain chain) {
        String token = chain.request.headers["X-Token"];
        if (token != "Test") {
          chain.abort(new Response()
            ..body = "{\"error\":\"Permission Denied\"}"
            ..statusCode = 401);
        }
    }
}

Você deve primeiro criar uma classe e anotá-la com @Interceptor, fornecendo dois parâmetros: quando ele será executado e sua prioridade. Em seguida, e isso é uma convenção, crie um método chamado intercept que recebe o parâmetro Chain. O objeto chain lhe dá acesso apenas ao Request, quando é um interceptor BEFORE, e acesso ao Request e Response quando é um interceptor AFTER.

Iniciando

Para fechar o exemplo, só precisamos iniciar o servidor, né? E isso é fácil! Basta criar uma instância de DarterServer, adicionar suas APIs e interceptors e mandar bala com start().

main() {
  new DarterServer()
    ..addApi(new MyDarterAPI())
    ..addInterceptor(new Authentication())
    ..start();
}

Vai me perguntar porque não fiz reflexão para encontrar as classes anotadas? Achei o mecanismo de mirrors do Dart muito massa, mas um pouco complicado de escanear o classpath de sua própria aplicação em busca das classes. Achei oneroso e propenso a erros. Até mesmo o RPC, do próprio Google, não faz isso. Então, resolvi ir na mesma onda deles! 🙂

Conclusão

Gostou? Achou a ideia interessante? Agora vem a parte mais legal: o projeto ainda está em estágios iniciais e, portanto, sua ajuda não é só permitida, é altamente desejada. Não precisa ser necessariamente com código, mas com sugestões de melhorias, testes e etc. Vamos lá? Manda suas dicas nos comentários!

Ah! Por último, porque o nome Darter? Em primeiro lugar, é óbvio, é pelo trocadilho com o nome da linguagem. Mas só isso não bastaria, eu também quis salientar a leveza e liberdade de um pássaro para voar da forma como quiser. Dois princípios que pretendo manter na biblioteca! O pássaro é esse da foto do post!

?????????

RESTful APIs com Dart

Já ouviu falar de Dart? É uma linguagem bem bacana, embora ainda ache ela um pouco “verbose”, criada pelo Google. A linguagem lembra um pouco Java, mas adiciona features que são extremamente interessantes e que facilitam substancialmente nossa vida. Alguns desenvolvedores torcem o nariz para Dart por sua semelhança com Java e Javascript, outros a adoram, exatamente por ter essa semelhança mas incluir features que o Java carece.

Qual meu lado? Eu acho Dart massa! Principalmente por eu ter programado em Java por tantos anos. Entretanto, Ruby ainda é minha linguagem favorita! Imbatível! 🙂 Mas, eu não vim aqui para exaltar nem Java, nem Ruby e nem Dart. Eu estou escrevendo esse post para tratar sobre três frameworks escritos em Dart que podem facilitar a vida de quem deseja criar uma API RESTful usando essa linguagem.

Algumas das vantagens de criar uma API com Dart é que a nuvem do Google está preparada para o Dart e a linguagem inclui features bem interessantes para isso. Até o momento, encontrei três ferramentas para essa tarefa: Redstone.dart, RPC (do Google) e Shelf Rest. São três boas ferramentas, mas, como veremos a seguir, carecem de algumas funcionalidades interessantes que encontramos em frameworks como o Grape, para Ruby.

Alerto que eu não fiz um estudo exaustivo sobre essas ferramentas. Fiz pequenos exemplos e tentei implementar algumas features que sempre busco em ferramentas como essas. É capaz de existirem outros problemas mas com os quais eu não me deparei. Isto pode ter acontecido porque meus exemplos eram simples, bem básicos e quando eu encontrava dois ou três problemas que, na minha humilde opinião, são falhas graves para a construção de APIs, eu parava de fuçar.

Antes de começarmos a falar sobre essas ferramentas, eu sugiro assistir o vídeo acima. Eu descobri essas ferramentas através desse vídeo. É extremamente indicado para quem quer começar a desenvolver APIs em Dart!

Redstone.dart

O Redstone.dart foi escrito por um brasileiro chamado Luiz Mineo. O Luiz esteve à frente do Redstone até a versão 0.5 mas não pôde continuar seu desenvolvimento e agora o Redstone está nas mãos de abnegados desenvolvedores que já estão trabalhando em melhorias e reformulações profundas. A nova versão, 0.6, já está em Beta e aparentemente, próxima de ser lançada.

A principal questão é que o Redstone não foi feito especificamente para criar APIs RESTful. Com ele você pode criar rotas e tratar essas rotas usando os principais métodos HTTP de forma muito, mas muito fácil mesmo! Eu criei uma API simples nele em 10 minutos! Mas, então, o que falta nele? Vamos enumerar:

  1. Não permite alterar dinamicamente o status code. Desta forma, você não consegue mudar de 200 para 201 em um PUT que cria um recurso. Eu já relatei uma issue no Issue Tracking deles e um dos desenvolvedores considerou a feature necessária. Ou seja, é provável que eles implementem isso no futuro. Embora eu esteja avaliando a possibilidade de mandar um Pull Request! 😛
  2. O Redstone não tem uma forma fácil de tratar a versão da sua API. Para APIs, isto é importantíssimo, pois APIs sempre evoluem e não dá para jogar a versão anterior fora e colocar uma nova de supetão.
  3. Respostas Parciais. Também não tem nenhum mecanismo que facilite construir respostas parciais. Isto teria que ser implementado “na mão”.
  4. Não retorna os status “padrão” para cada método HTTP. Por exemplo, é esperado que o método POST retorne o status 201 CREATED. O Redstone não retorna automaticamente o 201, no lugar, ele retorna 200. 

RPC

RPC, diferente do Redstone, foi feito para criar APIs RESTful. Esse era o objetivo quando criaram ele. O RPC foi criado pelo Google e foi a escolhida pelo cara do vídeo que postei no início do post. Mas, infelizmente, tem uma coisa que me irritou nela. O RPC inclui a versão da API na URI. Não encontrei outra forma. Eu prefiro, e acho mais elegante, tratar a versão no cabeçalho ACCEPT. Eu uso a URI apenas para endereçar recursos. Somente!

Sendo uma biblioteca feita essencialmente para construir APIs RESTful, eu esperava encontrar maior flexibilidade com relação a isso. Outro problema que encontrei foi a impossibilidade de alterar o status code dinamicamente. Procurei na documentação como fazer isso, mas não encontrei. Dei uma leve fuçada no código, mas também não encontrei.

Shelf RPC

Como o nome sugere, o Shelf Rest é um adendo ao Shelf para criar serviços RESTful. Esta foi a única ferramenta que eu não testei profundamente. Só dei uma fuçada na documentação, então, peço desculpas caso eu esteja falando merda aqui! 😛 Do que pude observar, ele carece de todos os problemas que citei para o RPC e o Redstone adicionado de mais um: não encontrei como criar rotas usando o método PATCH. Estranho, hein?

Outra coisa que achei bem estranha: eles definem anotações para os métodos HTTP: @Get, @Post, @Put e @Delete. Só que inventaram uma anotação @AddAll que está na mesma categoria das outras. Oi? Semanticamente, não faz o mínimo sentido, embora a funcionalidade pareça interessante.

Conclusão

Você deve estar se perguntando: maluco, você indicaria algum desses frameworks? Eu sou meio xiita nesse negócio de APIs REST, então, tenderia a dizer não. Mas, eu acredito que é possível sim criar boas APIs RESTful usando o Redstone. Pareceu a biblioteca mais promissora e com maior flexibilidade. Eles tem um mecanismo de plugin que achei interessante, pois dá para, por exemplo, criar um mecanismo para retornar Partial Responses.

Ou seja, até aqui eu indicaria o Redstone. A outra pergunta que me fariam é: você acha que Dart está pronto para construir APIs RESTful? Minha resposta é que a linguagem está sim. Ainda não temos um framework tão interessante como é o Grape em Ruby. Uma coisa não invalida a outra. Dart é sim interessante para essa tarefa, mas ainda precisamos de ferramentas mais adaptadas para isto. Então, vamos construir uma? Vamos ajudar o pessoal do Redstone? Ou criar um plugin lá?

Eu vou! 😛

315122-svetik

APIs RESTful com Grape – Parte 3

Este é mais um post da série APIs RESTful com Grape, o terceiro da série. No primeiro post, mostramos como montar seu ambiente e como estruturar seu projeto. Além disso, montamos uma API simples cujo o objetivo é prover dados sobre cervejas. Até aqui, temos apenas uma API funcional e provendo uma lista de tipos de cervejas. Adiante, já no segundo post, vimos como usar o gem grape-entity para evitar expor nossos Models através da API.

Continuando essa série, vamos agora implementar os métodos POST, PUT, DELETE e GET(id) para criar, atualizar, remover e obter uma cerveja e um tipo de cerveja específico. Por debaixo dos panos, também estaremos usando o DataMapper para realizar a persistência dos dados. Relembrando, pela terceira vez, este projeto está no Github. Sugiro que você baixe-o e utilize esta série de posts apenas como guia para entender o código fonte que está no projeto.

DataMapper

Conhece o DataMapper? Trata-se simplesmente de um framework para persistência de dados. Só isso mesmo. Caso não goste de frameworks deste tipo, você pode fazer tudo na unha, é problema seu. Ou, caso não goste do DataMapper, você também pode usar o ActiveRecord. Por fim, caso você não queira usar bancos de dados relacionais, você pode dar uma olhada no MongoMapper. Só aviso que nosso objetivo aqui não é detalhar como funcionam estas ferramentas. Talvez em um post futuro, mas não nesse! Neste caso, vamos fazer apenas o básico do básico para colocar o DataMapper funcionando neste projeto.

Instalando

Rápido e caceteiro! Digite gem install datamapper para instalar o DataMapper globalmente. Em seguida, atualize seu arquivo Gemfile, adicionando a linha gem ‘data_mapper’. Finalizando, execute bundle install para instalar os gems necessários para o projeto. Fim!

Alterando os Models

Agora, precisamos alterar nossos models para que eles tenham persistência de dados. Mas não se assuste, é coisa bem simples, como você pode ver na listagem de código abaixo.

require 'data_mapper'

module Models

  # Cervejas.
   class Cerveja
     include DataMapper::Resource

     property :id, Serial
     property :nome, String
     belongs_to :tipo
   end

  # Tipos de Cervejas
   class Tipo
     include DataMapper::Resource

     property :id, Serial
     property :nome, String
     has n, :cervejas
   end

end

O que nós fizemos? Primeiro, precisamos fazer um “require” do DataMapper logo no início do arquivo models.rb. Segundo, precisamos alterar nossas classes para incluir o DataMapper::Resource e definir as propriedades, que virarão colunas nas tabelas que representarão cada classe. Para definir as propriedades, usamos o método property, que recebe dois parâmetros: um Symbol que representa o nome da propriedade e o tipo da propriedade.  Observe que neste exemplo em específico, ainda precisamos fazer um relacionamento de “um-para-muitos” entre tipo e cerveja. Na classe Cerveja, informamos isto através da linha belongs_to :tipo, enquanto na classe Tipo, fizemos has n, :cervejas. Simplificando: um Tipo tem muitas cervejas e uma Cerveja tem apenas um Tipo.

Finalizando

Para colocar o DataMapper rodando, agora só precisamos definir o Adapter de banco de dados a ser usado e avisar a ele para criar automaticamente toda a estrutura do banco de dados. Como fazemos isso? Do modo mais simples possível: alterando nosso arquivo config.ru. Mas, antes disso, você precisará instalar e configurar um banco de dados de sua preferência. Para este artigo, usarei o MariaDB, herdeiro do MySQL. Por que? Porque sim e pronto.

Comece instalando o gem ‘dm-mysql-adapter‘ e não se esqueça de incluí-lo também no Gemfile, viu? Agora altere seu arquivo config.ru para ficar parecido com a listagem abaixo. Observe que adicionamos apenas quatro linhas. Primeiro, o require para o DataMapper. Segundo, informamos o banco de dados através do método setup, em seguida, chamamos o método auto_migrate! para criar a estrutura das tabelas automaticamente e finalizamos chamando finalize! Pronto! Cabô essa seção, ufa! Muito chata!

$:.unshift "./app"

require 'rack/cors'

require 'rubygems'
require 'grape'
require 'rack'
require 'grape-entity'
require 'data_mapper'
require 'api/base.rb'

DataMapper.setup(:default, 'mysql://seulogin:suasenha@localhost/bebumapi')
DataMapper::auto_migrate!
DataMapper::finalize

use Rack::Cors do
  allow do
    origins '*'
    resource '*', headers: :any, methods: [:get, :post, :put, :delete, :options, :patch]
  end
end

run API::Base

API de Tipos e Cervejas

Agora, que tal fecharmos toda a API de Tipos? Vamos lá. Vamos implementar mais 3 métodos nela. O primeiro método será responsável por obter um Tipo de cerveja a partir de um ID e está definido na linha que tem get ‘:id’ do. Observe que a String ‘:id’ informa que teremos uma rota /tipos/algoaqui. Ou seja, sempre que alguém tentar acessar http://localhost:9292/tipos/*, cairá neste método. E como podemos obter esse valor :id? Simples, usando o Hash chamado params. Simples demais! Agora só chamamos o DataMapper pedindo o Model que representa esse recurso.

Vamos ver o método POST? Observe que não passamos uma String igual a como fizemos com o get. Exatamente porque não precisa, já que queremos uma rota POST na URL http://localhost:9292/tipos. Quando alguém fizer um post nessa rota, também deve passar algumas coisas como parâmetro. Neste caso, o nome do Tipo da cerveja. A partir daí, fica tudo mais fácil! Só criamos um objeto Models::Tipo e mandamos o DataMapper salvar. De lambuja, retornamos a entidade criada.

module API

  module V1

    class Tipos < Grape::API

      resources :tipos do

        get do
          present Models::Tipo.all, :with => Entities::Tipo
        end

        get ':id' do
          present Models::Tipo.get!(params[:id]), :with => Entities::Tipo
        end

        post do
          tipo = Models::Tipo.new
          tipo.nome = params[:nome]
          tipo.save

          status 201
          header 'Location', "/tipos/#{tipo.id}"
          present tipo, :with => Entities::Tipo
        end

        put ':id' do
          tipo = Models::Tipo.get params[:id]

          if tipo.nil?
            status 201
            header 'Location', "/tipos/#{tipo.id}"
            tipo = Models::Tipo.new
          else
            status 200
          end

          tipo.nome = params[:nome]
          tipo.save

          present tipo, :with => Entities::Tipo
        end

        delete ':id' do
          status 204
          Models::Tipo.get!(params[:id]).destroy!
        end

      end

    end

  end

end

Mas, opa! Lembra que eu falei que iríamos fazer uma API seguindo os princípios REST? Então, é prudente que a gente também retorne o cabeçalho Location informando a URI do recurso que acabamos de criar. E o Grape nos ajuda substancialmente para fazer isso! Basta usar header ‘Location’, “/tipos/#{tipo.id}”. De brinde, embora não seja necessário, pois o Grape já faz isso em todo método POST, informamos que queremos retornar um status 201 CREATED na linha status 201. Diga se não é lindo isso!

E o DELETE? Moleza, companheiro! Basta criar o bloco DELETE parecendo com o GET anterior e remover a entidade. Ah! Só não se esqueça de definir o status como 204 NO CONTENT, viu? Vamos finalizar com o PUT? Ele é só um pouco mais chato. Mas nada demais. Lembre que o PUT deve verificar se o ID informado se refere a um recurso existente. Caso não se refira, devemos criar esse recurso.

No código, a única diferença é que checamos se o objeto é nil. Caso seja, mudamos o status para 201 CREATED e também retornamos o cabeçalho Location. Caso contrário, botamos o status para 200 OK. O resto do código é similar ao que fizemos para o método POST.

E como fica a API de Cerveja? Rapaz, idêntica a essa. Claro, temos que tratar algumas coisas específicas, como o relacionamento entre Cerveja e Tipo. Mas não é nada de outro mundo, como você pode ver na listagem abaixo e que eu não vou explicar porque você é inteligente e já entendeu tudo! 😛

Pronto! Cabô mais um artigo! Quer saber sobre o que escreverei no próximo? Vamos ver como tratar erros genéricos, como, por exemplo, quando um recurso não existe ou quando o usuário da API esqueceu de enviar um parâmetro. Não perdaum!

40-Tempranillo-grapes

APIs RESTful com Grape – Parte 2

Após um longo, longo, longo período, aqui estou eu de novo para fazer a segunda parte da série de artigos sobre a construção de APIs RESTful com Grape. Sem muita enrolação, vamos direto ao ponto! Relembrando, todo o código fonte está no Github.

app/api/v*/base.rb

No artigo anterior, eu não mostrei como fica o código dos arquivos base.rb que estão nos diretórios de cada versão de nossa API. Vou começar mostrando eles aqui, até mesmo porque, na versão anterior que está no Github, havia um pequeno problema: eu não tinha definido o formato padrão a ser usado para representar os recursos retornados por nossa API. Abaixo, temos o arquivo app/api/v1/base.rb. Não mostraremos o arquivo da versão 2, pois é idêntico a este.

require 'api/v1/cervejas'
require 'api/v1/tipos'
require 'models/model'
require 'api/v1/entities/entity'

module API

  module V1

    class Base < Grape::API       
      version 'v1', :using => :header, :vendor => 'alienlabz', :format => :json
      format :json

      mount API::V1::Cervejas => '/'
      mount API::V1::Tipos => '/'
    end

  end

end

Inicialmente, importamos os arquivos necessários para essa versão. Em seguida, criamos a classe Base, herdando de Grape::API, e definimos como acessar uma versão específica da API. Como eu já havia explicado isso no artigo anterior, vou só copiar e colar o que escrevi lá: definimos que a versão da API será obtida através do cabeçalho Accept do HTTP. Para que esta versão da API seja invocada, o cabeçalho Accept deverá estar escrito assim: application/vnd.alienlabz-v1+json. Isto é um padrão, não se preocupe em entender os motivos de ele estar definido assim. Obviamente, caso queira acessar outra versão da API, basta trocar o v1 por v2, por exemplo.

Pronto, esses arquivos contém apenas e unicamente isto! Difícil? Duvido!

As Entidades

A segunda ideia que trataremos nesse artigo são as entidades. Observe que no nosso arquivo app/api/v1/tipos.rb, no método get, retornamos um Array contendo uma única instância do Model que representa um tipo de cerveja, certo? Mas, será que essa é a melhor maneira? Eu acredito que não. E por diversos motivos. Vou citar só dois:

  1. Um model é a sua unidade de negócio e contém informações que você não quer ver expostas através da API.
  2. Não poluir seus models com informações sobre como eles serão expostos através de uma API RESTful. E se no futuro você também quiser expor através de uma API SOAP? Vai poluir esse model ainda mais?

Pensando nisso, a galera do Grape também criou o Gem grape-entity. Vamos começar instalando-o: gem install grape-entity. Em seguida, vamos abrir o arquivo app/api/v1/entities/entity.rb. Observe que este arquivo contém todas as nossas entidades, contudo, assim como ocorre com os seus modelos, você pode separar cada entidade em um arquivo específico. Talvez façamos isso no futuro.

Uma entidade é simplesmente uma classe que estende de Grape::Entity e que define quais atributos serão expostos através da API. É claro que ele não é apenas isso, pois existem dezenas de outras funcionalidades. Mas, para este artigo, vamos nos ater apenas à sua funcionalidade básica.

module Entities

  class Cerveja < Grape::Entity
    expose :id
    expose :nome
    expose :tipo
  end

  class Tipo < Grape::Entity
    expose :id
    expose :nome
  end

end

Note como usamos o método expose para informar quais atributos estarão disponíveis através de cada entidade. O Grape Entity é poderoso e nos permitir usar expressões mais complexas para definir se um atributo será exposto ou não. Por exemplo, através dele podemos aplicar a ideia de respostas parciais, conforme discutido neste artigo do Google. Não se preocupe, pois faremos isso no futuro.

Agora precisamos de apenas uma alteração a mais: informar na nossa API que queremos retornar uma entidade e não o model. Para isso, vamos abrir novamente o arquivo /app/api/v1/tipo.rb e fazer uma pequena alteração no método get, conforme vemos no código abaixo:

        get do
          tipo = Models::Tipo.new
          tipo.id = 1
          tipo.nome = 'Pilsen'

          present [tipo], :with => Entities::Tipo
        end

Notou a diferença? Está ali, na penúltima linha. Antes, retornávamos [tipo], e agora estamos usando a expressão present [tipo], :with => Entities::Tipo. Acho que é auto-explicativo, mas vamos lá! O método present é do Grape e recebe como parâmetro o recurso, no nosso caso uma lista de tipos, e a entidade que será usada para representar esse recurso. Simples assim!

restinpractice1

API RESTful

A onda de desenvolvimento de APIs está com força total, já observou? O assunto está em alta e muita gente está tentando entender o que é uma API, como desenvolver uma, quais as melhores práticas, qual a melhor linguagem, qual o melhor framework… Mas, por que APIs está tão em alta assim? Em minha humilde opinião, dois fatores são muito importantes para isso. O primeiro motivo são os dispositivos móveis, que ganharam uma força tremenda e praticamente todo sistema, por mais simples que seja, precisa ter uma versão mobile.

Neste cenário, é óbvio que não vamos construir um sistema “auto-contido” no dispositivo móvel. Todo bom desenvolvedor mobile sabe que esse tipo de aplicativo é apenas uma “casca”, uma interface para um sistema que está rodando em um backend, provavelmente na nuvem. O aplicativo móvel, então, se comunica com esse backend através de uma API, exibindo ou atualizando dados. O segundo fator são as redes sociais, exatamente porque elas são parte de nossas vidas e quase todo aplicativo desenvolvido hoje em dia requer algum tipo de interação mínima com uma rede. E essa interação é feita sempre através de APIs. Juntando esses dois fatores e, obviamente, muitos outros, temos de volta esse hype de APIs. Eu disse de volta?

Claro! Ou você não sabia que API é só um jeito diferente de chamar Web Services? Esse nome lhe lembra de algo? Talvez SOAP? Talvez RMI? Pois é. Nada de novo no quadrante! A única coisa que de fato é nova em tudo isso é a forma como as atuais APIs são construídas. Deixe-me lhe explicar um pouco: antes essas mesmas APIs eram construídas usando, por exemplo, o protocolo SOAP. Entretanto, o SOAP é um protocolo extremamente pesado. Ele define sua própria sintaxe e semântica e usa o HTTP apenas para transportar seu próprio pacote para um destino.

O SOAP também se baseia na ideia de RPC – Remote Procedure Call e, por isso, tem uma semântica diferente das APIs atuais. No SOAP, você imagina que existem objetos remotos e que você quer chamar métodos desses objetos, diferente das APIs RESTful, onde você tem recursos e operações executadas nesses recursos.

Enfim, o SOAP é um exemplo prático da má utilização do protocolo HTTP, que se torna um mero burro de carga. O SOAP, e muitos outros protocolos, não usam o HTTP ao máximo, com todas as suas propriedades e possibilidades. Resulta que o SOAP não é ideal para a comunicação com dispositivos móveis. Aliás, é horrível. Experiência própria.

Uma resposta às APIs SOAP são as APIs RESTful, que seguem, ou tentam seguir, os princípios REST descritos por Roy Fielding. APIs RESTful são mais leves e se encaixam perfeitamente no mundo Web. Elas usam as características do HTTP em sua plenitude. APIS RESTful não definem um protocolo próprio, pois o HTTP é só o que elas precisam. As APIs RESTful se moldam ao mundo Web, onde temos recursos (uma página, um arquivo, uma música, um vídeo…) e operações sobre esses recursos (visualizar, editar, apagar…). APIs RESTful são simples, fáceis de usar e criar, seguras, leves e elegantes.

Caso você esteja apenas iniciando neste mundo, sugiro que leia inicialmente o livro REST in Practice – Hypermedia and System Architecture. Link para a Amazon. É um excelente livro e que vale cada centavo gasto!

ruby

APIs RESTful com Grape – Parte 1

Não é novidade para ninguém qual é a minha linguagem de programação favorita ultimamente. Ruby, oras! Provavelmente, também não é mais novidade para ninguém que venho focado em um único assunto: desenvolvimento de APIs RESTful. Inclusive, fazendo palestras aqui em Salvador. Então, como juntar esses dois mundos (Ruby + APIs)? A resposta é Grape! Um framework espetacular, que provê uma DSL muito simples e que facilita brutalmente a vida dos desenvolvedores de APIs.

Entretanto, percebi um probleminha! Não encontrei um tutorial sequer na Internet, sobre esse assunto, escrito em português ou espanhol. Péssimo! Portanto, meu objetivo aqui é escrever uma série de publicações sobre como instalar, configurar e usar o Grape para criar suas APIs. Primeiro, será um post em português, depois, me arriscarei a escrever em espanhol também. Será duplamente útil, porque terei a oportunidade de por em prática meus estudos de espanhol. 🙂

API do Bebum

Nosso projeto será uma API para um sistema que disponibilizará informações sobre cervejas. Começaremos com apenas dois modelos: Cerveja e Tipos de Cervejas. Futuramente, poderemos avançar, incluíndo mais modelos e incrementando nossa API! Todo o código que vocês verão aqui estará no Github, no endereço https://github.com/marloncarvalho/bebum-api.

Preste atenção que estamos seguindo rigorosamente (ou o máximo que pudermos) o modelo REST para a criação de APIs. Observe também que estou criando Tags no repositório com os nomes das partes de cada artigo. Por exemplo, teremos a Tag Parte 1, Parte 2 e assim por diante!

Montando seu Ambiente

Sou fã de Mac de longa data, portanto, vou focar basicamente nesta plataforma. Mas, como Mac é um *NIX, a maioria das coisas que farei aqui são replicáveis em um ambiente Linux. Quanto aos usuários Windows… bom, aí não tenho muito a ajudar, pois já tem 10 anos que não uso esse ambiente. Inicialmente, você precisa ter o interpretador Ruby instalado. No meu caso, eu uso o RVM – Ruby Version Manager para esta tarefa. O RVM instala e gerencia as versões do Ruby que você tem em sua máquina. Sugiro fortemente usá-lo!

Instalando o Ruby com o RVM

Para instalar o RVM, conforme descrito na página deles, basta digitar no console:

\curl -sSL https://get.rvm.io | bash -s stable

Depois disso, vamos instalar o Ruby na versão 2.1.2 usando o comando:

rvm install 2.1.2

Com o Ruby instalado, vamos agora instalar o Gem do Grape digitando no console:

sudo gem install grape

Pronto, seu ambiente está montado para nosso primeiro projeto com Grape. Fácil, não?

Bundler

Você já conhece o Bundler? Ainda não? Que feio! O Bundler é um gerenciador de dependências para Ruby. Com ele, fica mais fácil você definir quais gems seu projeto necessita e baixá-los. Caso ainda não o tenha instalado, faça gem install bundler no seu console para instalá-lo. O Bundler espera que você tenha um arquivo Gemfile na raiz do seu projeto. Neste arquivo, você deve listar cada Gem que seu projeto depende. Uma vez que você cria este arquivo, basta digitar bundle install no console, dentro do diretório onde está o arquivo Gemfile, para que ele baixe as dependências.

Estrutura do Projeto

Eu poderia começar com uma estrutura extremamente enxuta, mas seria simplista demais e já existem dezenas de artigos em inglês ensinando a usar o Grape que já fazem isso, então… Nosso próximo passo agora é montar a estrutura do nosso projeto. Crie um diretório qualquer em sua máquina e monte uma estrutura de diretórios semelhante à da imagem abaixo. Você também tem a possibilidade de baixar essa estrutura direto do nosso repositório.

Estrutura detalhada de diretórios do nosso projeto.

Esta é uma estrutura que eu sugiro, mas não significa que você deve utilizá-la sempre. Fique à vontade para modificá-la, conforme suas necessidades. Outro detalhe digno de nota é que ainda faltam alguns diretórios nessa estrutura. Por exemplo, ainda precisamos dos diretórios db e spec, mas faremos isso nos próximos artigos.

Nesta estrutura, o diretório app conterá todas as classes relacionadas ao negócio da nossa aplicação. Este diretório é subdividido em api models, onde api manterá somente as classes responsáveis em manter a lógica da nossa API RESTful e models conterá as classes de modelo, onde estarão, de fato, nossas regras de negócio.

Já o diretório api é subdividido em outros dois subdiretórios, chamados v1 v2. Esta divisão é interessante para facilitar a criação de novas versões da nossa API. Observe que tanto dentro de app, como dentro de v1v2, existe um arquivo chamado base.rb. Eles estão aí para unir em um único ponto todas as APIs que disponibilizaremos. Não se preocupe se ainda está confuso, pois detalharemos esses arquivos com cuidado a seguir. Dentro dos diretórios v1 v2 ainda temos uma pasta entities, que será responsável em manter as classes que irão expor os dados do nosso sistema em um formato de recursos.

Finalizando, o diretório model não tem nenhum subdiretório. Todos os demais arquivos são velhos conhecidos de todo programador Ruby e não vou detalhá-los aqui!

Modelos

Vamos nos focar agora na pasta models, onde temos, até este momento, apenas um arquivo chamado model.rb. Este arquivo contém as nossas classes de modelo. Obviamente, você pode, caso prefira, separar as classes em arquivos distintos. Talvez façamos isso no futuro, entretanto, para simplificar, vamos deixar em apenas um arquivo.

module Models

   # Cervejas.
   class Cerveja
      attr_accessor :id, :nome, :tipo
   end

   # Tipos de Cervejas
   class Tipo
      attr_accessor :id, :nome
   end

end

Observe que são duas classes extremamente simples, ainda sem nenhuma lógica de negócio associada e também sem as informações de persistência. Vamos incrementá-las no futuro, entretanto!

Estrutura Geral da API

Vamos agora fazer nossa primeira API funcional. Vamos iniciar analisando a pasta api. Observe o arquivo base.rb. Ele é extremamente simples, pois serve apenas para agrupar TODAS as versões que estamos disponibilizando da nossa API. É óbvio, entretanto, que normalmente liberamos apenas duas versões por vez. Mas, caso seja necessário, esta estrutura nos permite disponibilizar quantas versões acharmos necessárias.

require 'api/v1/base'
require 'api/v2/base'

module API

   class Base < Grape::API
      mount API::V1::Base
      mount API::V2::Base
   end

end

Este arquivo tem um módulo chamado API e dentro dele há uma classe chamada Base que estende de Grape::API. Logo em seguida, montamos as APIs que queremos exibir. No nosso caso serão API::V1::Base e API::V2::Base. Como você deve estar imaginando, essas classes estão definidas nos arquivos /app/api/v1/base.rb /app/api/v2/base.rb. São duas versões da mesma API!

Agora, vamos bisbilhotar o arquivo /app/api/v1/base.rb. Ele tem um pouco mais de informações. Inicialmente, continuamos criando o módulo API, mas agora temos outro módulo dentro dele, chamado V1. Depois, definimos a classe Base, que monta as APIs de Cervejas e Tipos. Essas duas APIs estão definidas nos arquivos api/v1/cervejas.rb api/v1/tipos.rb.

Também definimos algumas informações importantes sobre essa API. Definimos que a versão da API será obtida através do cabeçalho Accept do HTTP. Para que esta versão da API seja invocada, o cabeçalho Accept deverá estar escrito assim: application/vnd.alienlabz-v1+json. Isto é um padrão, não se preocupe em entender os motivos de ele estar definido assim. Obviamente, caso queira acessar outra versão da API, basta trocar o v1 por v2, por exemplo.

Não entraremos em detalhes da estrutura do diretório v2, pois ele está exatamente da mesma forma que o v1, já que ainda não temos nenhuma intenção de lançar uma versão 2.0 da API.

API de Tipos de Cervejas

Analisemos agora o arquivo /api/v1/tipos.rb. Ele inicia, como deveria ser, com a definição dos módulos APIV1. Logo em seguida, cria a classe Tipos herdando de Grape::API. Lembre-se, toda classe que representa uma API deve herdar desta classe do Grape. Agora a mágica começa a acontecer. Observe a definição do bloco resources. Ele serve para definir um namespace, dentro do qual estaremos servindo dados sobre um determinado recurso que estará disponível através de nossa API. No nosso caso, temos um recurso chamado Tipos, certo? Portanto, usamos o símbolo :tipos para criar o bloco de recursos referentes ao recurso tipos. Trocando em miúdos, isto significa que teremos uma URL do tipo http://localhost:port/tipos. Seguindo, definimos outro bloco, agora chamado de get.

module API
   module V1
      class Tipos < Grape::API
         resources :tipos do
            # Obter uma lista de Tipos de Cervejas
            get do
               tipo = Models::Tipo.new
               tipo.id = 1
               tipo.nome = 'Pilsen'
               [tipo]
            end
         end
      end
   end
end

Observe atentamente esse método e tenha em mente que o Grape é uma DSL (Domain Specific Language). O que estamos fazendo nesta linha é chamar o método get (definido em Grape::API) passando como parâmetro a String ‘:id’ e um bloco de código que será chamado futuramente. Parece confuso? Mas é mais simples do que você pensa e é por isso que eu amo Ruby! O que estamos fazendo é informando ao Grape que temos uma rota ‘http://dominio/tipos/id’, acessível através do método GET do HTTP. Dentro do bloco de código, você escreverá o código que tratará toda requisição que chegar a essa rota através de um GET. Simples, certo? Lógico que é!

Nossa primeira API RESTful com Grape está quase pronta!

Configurando o config.ru

Ainda precisamos configurar o arquivo config.ru para conseguirmos rodar nosso projeto. Este arquivo contém os requires mais genéricos, necessários para rodar nosso projeto, como o graperubygems e rack. Depois, usamos o CORS para liberar as requisições cross-origin para todos os métodos HTTP (GET, POST,…). No final, rodamos a API com run API::Base. Observe que só precisamos de um require de módulos de nosso projeto: require ‘api/base.rb’.

$:.unshift "./app"

require 'rack/cors'

require 'rubygems'
require 'grape'
require 'rack'
require 'grape-entity'

require 'api/base.rb'

use Rack::Cors do
   allow do
      origins '*'
      resource '*', headers: :any, methods: [:get, :post, :put, :delete, :options, :patch]
   end
end

run API::Base

Feito isto, agora vá no seu console e digite rackup. Sugiro instalar o Chrome junto com o plugin Postman. É um excelente plugin para executar chamadas a APIs RESTful. Veja abaixo como chamar nossa API na versão 1.

Usando o Postman para chamar nossa API.

 Pronto, meu caro, já temos nossa primeira versão da API executando! Não acredita? Testa aí! Nos próximos artigos, vamos fuçar mais o Grape, usando mais features dele. O objetivo deste primeiro artigo foi criar a estrutura e colocar uma primeira API simples executando!