Faça uma API da web indolor em Ruby

Claro, você pode implementar uma API de várias maneiras, incluindo algumas muito dolorosas que envolvem nada além da funcionalidade básica do Rails.

Mas por que fazer isso quando você pode se divertir criando sua API?

O Grape fornece uma DSL fácil de escrever e ler para a criação de APIs não REST, REST ou REST, incluindo até mesmo um controle de versão indolor. Se você estiver usando Ruby para seu aplicativo principal, sua API Grape pode ser facilmente montada ao lado ou dentro de qualquer aplicativo Rack (incluindo aplicativos Rails).

Precisa de uma API inútil para retornar o tempo de época? Muito fácil:

module TickTock
  class API < Grape::API
    version 'v1', using: :path
    format :json

    get "epoch" do
      Time.now.to_i
    end
  end
end

Montado no Rails, é muito fácil vomitar seus objetos ActiveRecord:

class QuoteAPI < Grape::API

  # ...

  resource :quotes do
    get :random do
      Quote.find_random
    end
  end

  # ...

end  

Et voila, JSON:

{
  "id": "42",
  "uid": "92cfceb39d57d914ed8b14d0e37643de0797ae56",
  "text": "There is nothing to fear but bears on skates.",
  "author": "Oscar Wilde",
  "truthiness": "true",
  "year": "2013"
}

“Mas espere”, você pode estar dizendo, “meu modelo de objeto está cheio de dados que não quero expor!” Isso também é fácil de lidar (em vários sabores, nem menos). O Grape oferece um plugin opcional para definir Entidades – isto é, os dados que você deseja expor e (opcionalmente) qualquer transmogrificação necessária para estar apresentável. Digamos que não queremos revelar que algumas citações são falsas ou o fato de que podem ter sido escritas um século depois da morte do suposto autor. E digamos que padronizamos o uso do UID para todos os acessos à API.

Podemos simplesmente incorporar uma definição de entidade em nossa classe de modelo:

class Quote < ActiveRecord::Base

  # ...

  class Entity < Grape::Entity
    expose :uid, :text, :author
  end

end

E blammo:

{
  "uid": "92cfceb39d57d914ed8b14d0e37643de0797ae56",
  "text": "There is nothing to fear but bears on skates.",
  "author": "Oscar Wilde"
}

Não é HATEOASy o suficiente para o seu gosto? É fácil implementar ideias do HATEOAS usando apenas o Grape, mas você também pode trabalhar de maneira mais inteligente e estender seus recursos com o Roar ou outros apresentadores hipermídia.

Grape tem um DSL simples, ampla compatibilidade com add-ons e é facilmente extensível. Experimente o seu próximo projeto de API; talvez você descubra que construir uma API incrível e compatível com versões anteriores é muito mais fácil do que você esperava.