?????????

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…

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!

ruby

Rundown on Grape Related Articles

My journey on API development started last year when I had to develop an API for a startup that I was involved with. Since then I’ve been intensively studying it through reading lots of articles and books. I built my first API using Java, even though it’s not my favorite language. To be honest, these days I’ve been shying away from projects where Java is the main language, however it was a great experience because I was able to learn lots of good practices for creating RESTful APIs.

And what’s my favorite language? If you’re following me on Twitter, you know that it’s Ruby. It was about three years ago when I was first introduced to Ruby, and since then I’ve been using it for most of my projects. Why Ruby? Because it’s the most elegant and beautiful language ever created. The worst thing about being a Ruby enthusiast is that everybody thinks you’re a Rails expert. I’m not. In fact, I have never used Rails.

Having said that, you might be wondering what I’ve been using to create my APIs. The answer is Grape: a simple and straightforward DSL that enormously simplifies the API developer’s life. This is not a step-by-step article on how to create APIs using Grape. Instead, I’m going to briefly lay out and comment on some articles and blog posts I’ve came across during these last months. I’m really surprised by the fact that there are only a few articles about Grape available on the Internet, and this is my motivation for writing this post.


Official Grape’s Site
https://github.com/intridea/grape

You haven’t ever heard of Grape? Then the first thing you should read is its official documentation. Every article I’m going to list from this point forward will be based on the assumption that you already know how to set up your Ruby and Grape environments. For this reason, it’s really important that you start reading it first if you’re new to this world. The documentation is simple and easy to understand.


Introduction to building APIs with Grape
http://codetunes.com/2014/introduction-to-building-apis-with-grape/

If you’ve already gotten the hang of programming in Ruby, and you know how to install Grape, then it’s time to read more specific and detailed articles. This one was published by Codetunes and describes how they built their API using Grape. It’s a good article despite the fact that they’re using some conventions that I personally don’t like, such as putting the API versioning information into the URI.

You must take into account, however, that they’re using Grape alongside Rails. Still, it’s not mandatory, and in my opinion you shouldn’t do this if the API which you’re planning to build doesn’t require all of the features and resources provided by Rails.


Build REST APIs with Grape
http://code.tutsplus.com/courses/build-rest-apis-with-grape

It’s a series of fourteen video lessons explaining how to build REST APIs with Grape. I haven’t watched every lesson, but it seems to be a very detailed step-by-step tutorial. Unfortunately, they provide only the first two videos for free.


Building RESTful API using Grape in Rails
http://funonrails.com/2014/03/building-restful-api-using-grape-in-rails/

A simple but useful article written by Sandip. Sandip doesn’t waste your time with misleading concepts and unnecessary explanations on how Grape works. He dives into the code in the first lines of his article. Again, take into account that he’s using Grape alongside Rails.


The 10 Minute API: Getting an API Up and Running in 10 Minutes with 3scale, Grape and Heroku
http://www.3scale.net/2012/06/the-10-minute-api-up-running-3scale-grape-heroku-api-10-minutes/

This is a 10 minutes hands-on video explaining how to build and deploy Grape based APIs on Heroku, one of the leading cloud host solutions on the market. I have some APIs running there and I strongly recommend their services. And no, they’re not paying me to write this, ok? :)

 The last thing worth mentioning about this article is the fact that they’re using their own API Management solution to authenticate each API call. Have you ever heard of the term API Management? I won’t explain it in this post because it deserves its own article. Instead, take a look at this article.


Building Modular APIs with Grape and Rails
http://priyaaank.tumblr.com/post/34018821171/building-modular-apis-with-grape-and-rails

This is the most detailed and interesting article out of all which I’ve listed so far. Priyank Gupta have written a detailed post explaining how he built his API using Grape, Rails and MongoDB.