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!

darts-copy

Dart: Syntax Sugar!

Que Dart é bacana, isso todo mundo sabe, certo? Mas, por que Dart é bacana mesmo? Um dos motivos é o que chamamos de syntax sugar. O que é isso? São facilitadores que a linguagem traz para que você faça tarefas muito comuns de forma mais fácil, com menos linhas de código. Algumas pessoas acham que syntax sugar é para os fracos. Outros dizem que é pura frescura. Ah vai, para! Se uma linguagem me dá uma forma de fazer uma coisa com menos trabalho, é claro, óbvio, cristalino, inteligente e outros mil bons adjetivos que eu quero usar isso!

Então, vamos começar falando sobre os syntax sugar que o Dart fornece para…

Construtores

Imagine, por exemplo, que você queira criar um construtor que recebe dois parâmetros e que atribui esses dois parâmetros para dois atributos que tem o mesmo nome. Trata-se de uma tarefa bem comum, certo? Então, porque não facilitar? Dart facilita. Vejamos como:

class Pessoa { 
   String nome; 
   String endereco; 

   Pessoa(this.nome, this.endereco); 
}

Pessoa marlon = new Pessoa("Marlon", "Rua dos Dartisans");

Lindo, não é? Observe que sua classe em Dart tem dois atributos e apenas um construtor, que recebe como parâmetro o nome e o endereço e já atribui o valor destes dois parâmetros para os atributos. Outro detalhe importante: essa atribuição ocorre antes de o corpo do construtor ser executado! Mas, peraí, e se eu precisar colocar um código no corpo desse construtor? Sem problemas.

class Pessoa { 
   String nome; 
   String endereco; 

   Pessoa(this.nome, this.endereco) {
      if(this.nome == "Marlon") {
         this.nome = "Marlon S. Carvalho";
      }
   }
}

Pessoa marlon = new Pessoa("Marlon", "Rua dos Dartisans");

Agora, e se sua classe herda de uma classe-pai e você precisa chamar o construtor do pai? Muito simples, meu caro, pois basta colocar um logo depois do construtor e chamar o construtor do pai. Observe também que você pode continuar usando a atribuição que vimos no exemplo anterior. Olha esse exemplo:

class Pessoa { 
   String nome; 
   String endereco; 

   Pessoa(this.nome, this.endereco);
}

class PessoaInteligente extends Pessoa {
    double qi;

    PessoaInteligente(nome, endereco, this.qi): super(nome,endereco) {
    }
}

Operador em Cascata

O operador em cascata é outro syntax sugar bem bacana. Quem nunca se deparou com a situação em que você precisa chamar diversos métodos de um objeto em sequência? Isso sempre acontece, né não? Principalmente quando você está inicializando um model ou entity e atribuindo aos seus atributos valores oriundos de um formulário HTML.

Pessoa pessoa = new Pessoa();
pessoa
    ..nome = "Marlon"
    ..endereco = "Rua dos Dartisans"
    ..save();

Métodos Assíncronos

Esta é bem recente e eu o considero como um syntax sugar também. Para você entender bem esse syntax sugar, lembre-se de como você trata requisições assíncronas com Javascript. Lembrou? Horrível, certo? Em Javascript temos o conhecido callback hell. Você precisa encadear um monte de funções de callback para atender a duas ou três chamadas assíncronas. Algo assim:

funcao_assincrona("param1", function(resultado) {
    funcao_assincrona2(resultado, function(resultado2) {
        funcao_assincrona3(resultado2, function(resultado3) {
            // Enfim, podemos fazer algo!
        });
    });
});

Meu amigo, esse código aí é feio demais! Nas primeiras versões do Dart, você também precisava fazer algo parecido com isso. A única diferença é que nós tínhamos a classe Future, mas a ideia era a mesma. E como o Dart resolveu isso? Com a biblioteca dart:async. Olha como as coisas agora ficaram lindas!

var resultado1 = await funcao_assincrona("param1");
var resultado2 = await funcao_assincrona2(resultado1);
var resultado3 = await funcao_assincrona3(resultado2);

Muito melhor, não? Com await, você programa quase como se estivesse programando um código síncrono. Quer saber mais sobre isso? Clica aqui.

Finalizando

Você acha que esqueci de citar alguma outra syntax sugar bacana do Dart? Então deixa um comentário! Eu adicionarei sua sugestão no artigo e com a devida citação para o autor.

?????????

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! :P
  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! :P 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! :P

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! :P

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!

what-is-a-ruby-gem

Eventioz Gem: API Wrapper para Ruby

Nasceu. Meu primeiro Gem para Ruby debutou no mundo. E sua concepção partiu de uma necessidade muito simples: eu precisava obter informações sobre os ingressos vendidos por um evento dentro da plataforma do Eventioz. Quer saber porque eu preciso obter essa informação? Por enquanto, é segredo! Mas em breve você saberá! Voltando ao Gem, trata-se de um simples wrapper, escrito em Ruby, que tenta facilitar a vida de quem quer acessar a API do Eventioz.

Infelizmente, após uma rápida pesquisa no Github e Google, não encontrei uma alma santa que tenha feito este trabalho. Restou para mim, então! O único porém, até o momento, é que ainda não fiz os testes. É, eu sei. Isso é feio e tal. Mas dá um desconto, vai. Eu fiz com pressa. Oi? É verdade, isso não é desculpa. Vamos mudar de assunto?

O Gem já se encontra disponível no Ruby Gems e seu código fonte está disponível no Github: https://github.com/marloncarvalho/eventioz. Não vou colocar informações sobre como utilizá-lo, pois tem tudo isso na página do Github. Acessa lá! Aproveita e, sem querer, aperta naquele botão “star” também. Aproveita logo e diz que eu sou lindo também! :P

maxresdefault

A Quarta do Wear

Eu e o Moto 360

Quem me acompanha nas redes sociais já sabe de minha saga para comprar um Moto 360! E você pensa que eu queria comprar ele só para dizer que tenho um? É, tudo bem, admito que foi por isso também. :) Mas como bom desenvolvedor nerd e sempre fã das tecnologias do Google, eu queria programar nessa plataforma e não tem motivação maior e melhor do que ter um dispositivo em mãos, certo? Claro que sim!

O que eu acho dos Wearables?

Os Wearables são, em minha humilde opinião, um caminho sem volta. Muita gente criticou os smartphones e/ou tablets, alegando que eram uma moda passageira. Como todo mundo viu, quebraram a cara feio. Vejo muita gente criticando os smartwatches, com alegações do tipo “sem utilidade”, “desnecessário”, “funcionalidades bobas”, “só pra tirar onda”… e vão quebrar a cara da mesma maneira. O mais engraçado é que algumas desses críticos já usaram ou usam um relógio cuja única funcionalidade é mostrar as horas. haha! :P

Eu admito que nunca usei relógios de pulso e o motivo era bem simples: depois dos smartphones, passei a encarar os relógios como apenas um acessório estético. A partir dos smartwatches, entretanto, isso tende a mudar, pois agora não é apenas uma questão de olhar as horas. Os smartwatches lhe trazem informações relevantes, contextualizadas e de forma extremamente prática, sem necessidade de puxar um celular do bolso.

Vamos Desenvolver?

Bom, mas porque cargas d’água eu fiz esse post cheio de blá blá blá? É para convidar você, caro amigo desenvolvedor que reside em Salvador e RMS, para estudar o desenvolvimento de aplicativos para Android Wear junto comigo. No dia 26 de novembro de 2014 estaremos eu e Wilson no Salvador Shopping no bar Chalezinho, às 19:00, esperando por você. Vamos conversar um pouco sobre essa plataforma, instalar o ambiente de desenvolvimento, compartilhar ideias de aplicativos e, quem sabe, já iniciar a desenvolver alguma coisa?

Eu e Wilson já estamos com um Moto 360 em mãos e levaremos para lá. Aos curiosos, podem ir lá dar uma sacada e conversar junto com a gente. Não será nada formal. Ao contrário, será totalmente informal. Sem planejamento. Vamos sentar na mesa, bater um papo e trocar ideias! Estão todos convidados para o primeiro Quarta do Wear, que será contínuo! Espero vocês lá! Não perdaum!

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!

journodevswap

Comunidades de Desenvolvedores

“Tem tanta tecnologia, não sei o que estudar!”. Eu já ouvi essa frase um montão de vezes e vinda quase sempre de estudantes de computação que estão preocupados com a enxurrada de siglas e possibilidades que existem na nossa área. Enquanto estamos cursando a faculdade, já estamos também nos preocupando em como vamos nos inserir neste mercado. Estudo Java para conseguir um emprego legal? Será que Ruby tem mercado? Será que é importante eu aprender como usar a Nuvem da Amazon? Por que não Python? Android ou iOS?

Infelizmente, em minha humilde opinião, esse cenário é agravado ainda mais pelo nosso modelo de ensino vigente, que nos impõe a escolha de uma profissão exatamente no momento de nossas vidas em que temos mais dúvidas! Já foi difícil escolher em qual faculdade entrar e, agora que escolhi computação e desenvolvimento, você ainda me diz que tem Java, Python, Frameworks, Nuvem, Android, iOS, Mobilidade, J2EE, Ruby, API, Mainframe… aaaaaaaahhhhh! É, meu caro, no início isso é desesperador mesmo. Eu já passei por isso e também fiquei tonto em ver tantas siglas e possibilidades de carreira.

Só que no decorrer desses quase 20 anos de “militância” no mundo da tecnologia, algumas coisas começaram a ficar mais claras para mim. Aprender uma tecnologia é importante. Tornar-se referência em algo também. Mas tem algo que acho ainda mais importante e que gostaria de compartilhar com vocês.

A dica é simples: dê mais atenção às comunidades de desenvolvedores de sua região. Dê mais atenção aos eventos em sua área, principalmente aqueles feitos por pessoas compromissadas em desenvolver a comunidade local. Quando você está em contato com pessoas inteligentes e focadas, você tende a crescer junto, absorvendo os conhecimentos dessas pessoas. Só que mais importante que absorver, é também ser um difusor de conhecimentos. Isso é importante para que você não apenas seja um sanguessuga, mas um potencial “broadcaster” desses conhecimentos que você adquire.

Mesmo em nossa área, onde temos que trabalhar diariamente com máquinas, as pessoas ainda são o fator mais importante. É com pessoas que você forma sua rede de contatos. É com pessoas que você adquire conhecimentos de forma mais rápida, divertida e agradável. É com gente que você marca aquela cervejinha e lorota após um evento sinistro onde você aprendeu um monte de coisa legal. É nesses eventos que você se mantém atualizado, mesmo que por alto, sobre o que está acontecendo. É nesses eventos e comunidades que você encontra tecnologias que pode se tornar um Jedi de forma mais fácil, divertida!

As comunidades são um fator chave, de extrema importância, para o ecossistema de desenvolvedores de uma região. É nos eventos que essas comunidades fazem que você forma amizades. É nesses eventos que você faz seu networking, demonstra suas habilidades para o mercado, torna-se conhecido, torna-se um difusor de ideias e alguém que todos querem ouvir. Dê mais atenção a nossas comunidades locais! Sério! Isso é importante não só para você, mas para a seu estado, cidade, bairro, rua…