Designing APIs with Ruby

Diseño de APIs con Ruby
Edwin Cruz @softr8

#SGRuby

Friday, June 15, 2012

PLAN

• Que es una API

• Como implementar una buena API

• Usando Ruby on Rails para implementar una API

• Patrones de diseño


“ Application
Programming
Interface

“

API

Es una manera para comunicar
dos aplicaciones entre ellas.


TIPOS DE API

• Library

• SDK

• Web services


PRIMERAS API - SOAP

Simple
Object
Access
Protocol


REST

REpresentation
State
Transfer


CRUD

Create Altas
Read Bajas
Update Cambios
Delete Consultas


REST ⋍ CRUD


REST ⋍ CRUD

Recursos a través de URI
Uso de verbos HTTP


REST-ISH + JSON


REST-ISH + JSON

=


REST-ISH + JSON

=
Cosas Increibles


RECURSO


RECURSO

Cualquier cosa expuesta mediante web


RECURSO

Tienen una representación en datos


RECURSO

Tienen una representación en datos
Con un servicio web intercambiamos
representaciones de recursos


REQUISITOS REST


REQUISITOS REST
Separación de responsabilidades


REQUISITOS REST
Cliente/Servidor


REQUISITOS REST
Cliente/Servidor
Sin estado


REQUISITOS REST
Cliente/Servidor
Sin estado
“Cacheable”


REQUISITOS REST
Cliente/Servidor
Sin estado
“Cacheable”
Sistema a capas


REQUISITOS REST
Cliente/Servidor
Sin estado
“Cacheable”
Sistema a capas
Interface uniforme


¿PORQUÉ UN API?


¿PORQUÉ UN API?

Aumenta la ﬂexibilidad de un servicio


¿PORQUÉ UN API?

Aumenta la utilidad de un servicio


¿PORQUÉ UN API?

Libera los datos de usuario


¿PORQUÉ UN API?

Libera los datos de usuario
Proporciona valor de negocio


¿QUÉ
CARACTERÍSTICAS?


¿QUÉ
CARACTERÍSTICAS?
Fácil de implementar y mantener


¿QUÉ
CARACTERÍSTICAS?
Buen rendimiento


¿QUÉ
CARACTERÍSTICAS?
Buen rendimiento
Escalable


¿QUÉ
CARACTERÍSTICAS?
Buen rendimiento
Escalable
Fácil de entender y usar


¿CUÁLES SON LOS
RETOS?


¿CUÁLES SON LOS
RETOS?

La red es un eslabón débil


¿CUÁLES SON LOS
RETOS?

API incompleta pone estrés en el cliente


¿CUÁLES SON LOS
RETOS?

API incompleta pone estrés en el cliente
Administrar Cambios


DISEÑAR UNA BUENA
API


CONVENCIONES REST


REST ⋍ CRUD

GET /api/products #Listado
{"products"
:

[

{"product"
:
{
"id"
:
1,
"name"
:
"Producto
1",
"status"
:
"archived"}
},

{"product"
:
{
"id"
:
2,
"name"
:
"Producto
2",
"status"
:
"active"

}
}

]
}


REST ⋍ CRUD

GET /api/products/2 #Ver

{"product"
:
{
"id"
:
2,
"name"
:
"Producto
2",
"status"
:
"active"

}
}


REST ⋍ CRUD

POST /api/products #Crear

{

"name"
:
"Producto
2"
}


REST ⋍ CRUD
PUT /api/products/2 #Actualizar

{

"name"
:
"Producto
dos"
}


REST ⋍ CRUD
DELETE /api/products/2 #Eliminar


VERSIONANDO TU API

• API Interna (entre aplicaciones)

• API Externa (aplicacion movil ? )

• API Usuarios (publico en general)


VERSIONANDO TU API

/int/api/products
/ext/api/products
/pub/api/products


VERSIONANDO TU API

/int/api/products?version=2
/ext/api/products?version=2
/pub/api/products?version=2


VERSIONANDO TU API

/v2/int/api/products
/v2/ext/api/products
/v2/pub/api/products


MUNDO IDEAL


MUNDO IDEAL

Uso de: Accept Header


MUNDO IDEAL

Uso de: Accept Header

Accept: application/vnd.mycompany.com;version=2,application/json


CODIGOS HTTP
200 OK
201 Created
202 Accepted

400 Bad Request
401 Unauthorized
402 Payment Required
404 Not Found
409 Conﬂict
422 Unprocessable Entity

500 Internal Server Error
503 Service Unavailable

CODIGOS HTTP

HTTP/1.1 401 Unauthorized

{
“errors”: [
“api_key not found”
]
}


CODIGOS HTTP

{
“errors”: [
“api_key no valida”,
“api_key no puede contener
espacios”
]
}


CODIGOS HTTP

{
“errors”: [
“api_key no encontrada, por favor
visita http://account.myapp.com/api para
obtenerla”
]
}


CODIGOS HTTP
HTTP/1.1 400 Bad Request

{
“errors”: [
“Estructura JSON no valida”,
“unexpected TSTRING, expected ‘}’ at
line 2”
]
}


DOCUMENTACION
HTTP/1.1 422 Unprocessable Entity

{
“errors”: [
“vendor_code: no puede estar vacio”
],
“documentacion”: [
“vendor_code”: [
“descripcion” : “Codigo asignado por proveedor”,
“formato” : “Combinacion de tres letras seguidas de 4
numeros”,
“ejemplo” : “SOL1234”
]
]
}


CODIGOS HTTP

HTTP/1.1 503 Service Unavailable

{
“messages”: [
“En mantenimiento”
]
}


OPCIONES AVANZADAS

• Simuladores

• Autenticación

• Validadores

• Limite de uso

• Rapidez

• Balanceo


USANDO RUBY ON
RAILS PARA
IMLEMENTAR UNA API


APIS ON RAILS - REST
MyApp::Application.routes.draw do
resources :products
end

products GET /products(.:format) products#index
POST /products(.:format) products#create
new_product GET /products/new(.:format) products#new
edit_product GET /products/:id/edit(.:format) products#edit
product GET /products/:id(.:format) products#show
PUT /products/:id(.:format) products#update
DELETE /products/:id(.:format) products#destroy


APIS ON RAILS - REST
scope ‘/api’ do
resources :products
end
end

products GET /api/products(.:format) products#index
POST /api/products(.:format) products#create
new_product GET /api/products/new(.:format) products#new
edit_product GET /api/products/:id/edit(.:format) products#edit
product GET /api/products/:id(.:format) products#show
PUT /api/products/:id(.:format) products#update
DELETE /api/products/:id(.:format) products#destroy


APIS ON RAILS -
gem 'versionist'
VERSIONES
api_version(:module => 'V1', :path => 'v2') do
resources :products
end
end

v2_products GET /v2/products(.:format) V1/products#index
POST /v2/products(.:format) V1/products#create
new_v2_product GET /v2/products/new(.:format) V1/products#new
edit_v2_product GET /v2/products/:id/edit(.:format) V1/products#edit
v2_product GET /v2/products/:id(.:format) V1/products#show
PUT /v2/products/:id(.:format) V1/products#update
DELETE /v2/products/:id(.:format) V1/products#destroy


APIS ON RAILS,
CONTROLADOR
class V2::ProductsController < ApplicationController
respond_to :json
def index
@products = V2::Product.paginate(:page => (params[:page] || 1),
:per_page => (params[:per_page] || 100)).all
respond_with @products
end
def show
@product = V2::Product.find(params[:id])
respond_with @product
end
def update
@product.update_attributes(params[:product])
respond_with @product
end
def destroy
respond_with @product.destroy
end
end


APIS ON RAILS -
MODELO
class V2::Product < Product

JSON_ATTRIBUTES = {
properties: [
:id,
:upc,
:sku,
:list_cost,
:color,
:dimension,
:size,
:created_at,
:updated_at,
],
methods: [
:units_on_hand
]
}

end


APIS ON RAILS,
CONTROLADOR
gem ‘rabl’
respond_to :json, :xml
def index
end
def show
end
def update
end
def destroy
render json: {}, status: @product.destroy ? :ok : :unprocessable_entity
end
end


APIS ON RAILS
VISTAS
#app/views/api/v3/products/index.rabl

collection @products
attributes :id, :name, :status
node(:url) {|product| product_url(product) }
node(:current_stock) {|product| product.variants.map(&:on_hand).sum }
child :variants do
attributes :upc, :color, :size, :on_hand
end

{"products"
:

[

{"product"
:
{
"id"
:
1,
"name"
:
"Producto
1",
"status"
:
"archived",
“current_stock”
:
10,

“variants”
:
[
{“upc”
:
“ASDFS”,
“color”
:
“negro”,
“size”
:
“M”,
“on_hand”
:
10}
]

}

}

]
}


APIS ON RAILS
VISTAS
gem ‘jbuilder’
Jbuilder.encode do |json|
json.content format_content(@message.content)
json.(@message, :created_at, :updated_at)

json.author do |json|
json.name @message.creator.name.familiar
json.email_address @message.creator.email_address_with_name
json.url url_for(@message.creator, format: :json)
end

if current_user.admin?
json.visitors calculate_visitors(@message)
end

json.comments @message.comments, :content, :created_at

end


APIS ON RAILS
VISTAS

gem ‘active_model_serializer’
class PostSerializer < ActiveModel::Serializer
attributes :id, :body
attribute :title, :key => :name

has_many :comments

def tags
tags.order :name
end
end


APIS ON RAILS
SEGURIDAD
Devise
Autenticacion Flexible para aplicaciones Rails
Compuesta de 12 modulos: database authenticable,
token authenticable, omniauthable, conﬁrmable,
recoverable, registerable, trackable, timeoutable,
validatable, lockable


APIS ON RAILS
SEGURIDAD
gem ‘rabl’
before_filter :authenticate_user!
respond_to :json, :xml
def index
end
def show
end
def update
end
def destroy
render json: {}, status: @product.destroy ? :ok : :unprocessable_entity
end
end


APIS ON RAILS
PRUEBAS
describe V3::ProductsController do

before do
@request.env["HTTP_ACCEPT"] = "application/json"
end

describe "#index" do
context "cuando no se pasa ningun atributo" do
it "regresa los registros en paginas" do
get :index
response.should be_success
data = JSON.parse(response.body)
Product.count.should > 0
data['products'].length.should == Product.count
end
end
end
end


APIS ON RAILS
PRUEBAS

before do
end

describe "#show" do
context "pasando un id inexistente" do
it "responde con http 404 y un mensaje de error" do
get :show, id: -1
response.code.should == "404"
JSON.parse(response.body)['error'].should == "ActiveRecord::RecordNotFound"
JSON.parse(response.body)['message'].should == "Couldn't find Product with
id=-1"
end
end
end
end


APIS ON RAILS
PRUEBAS

before do
end

describe "#create" do
context "con malos atributos" do
it "responde con un error" do
post :create, product: {bad_key: "foo"}
response.code.should == "400"
json_response = JSON.parse(response.body)
json_response['error'].should == "ActiveRecord::UnknownAttributeError"
json_response['message'].should == "unknown attribute: bad_key"
end
end
end
end


APIS ON RAILS
PRUEBAS

before do
end

describe "#create" do
context "con atributos correctos" do
it "responde correctamente y crea el producto" do
expect {
post :create, product: {name: "productito"}
}.to change(Product, :count).by(1)
end
end
end
end


RAILS A DIETA


RAILS A DIETA

Rails es modular


RAILS A DIETA

Rails es modular
Para crear APIs, algunos Middlewares no son
necesarios


RAILS A DIETA

Rails es modular
Para crear APIs, algunos Middlewares no son
necesarios
rails-api


<Module:0x007ff271221e40>,
ActionDispatch::Routing::Helpers,
#<Module:0x007ff2714ad268>,
ActionController::Base,
ActionDispatch::Routing::RouteSet::MountedHelpers,
HasScope,
ActionController::Compatibility,
ActionController::ParamsWrapper,
ActionController::Instrumentation,
ActionController::Rescue,
ActiveSupport::Rescuable,
ActionController::HttpAuthentication::Token::ControllerMethods,
ActionController::HttpAuthentication::Digest::ControllerMethods,
ActionController::HttpAuthentication::Basic::ControllerMethods,
ActionController::RecordIdentifier,
ActionController::DataStreaming,
ActionController::Streaming,
ActionController::ForceSSL,
ActionController::RequestForgeryProtection,
AbstractController::Callbacks,
ActiveSupport::Callbacks,
ActionController::Flash,
ActionController::Cookies,
ActionController::MimeResponds,
ActionController::ImplicitRender,
ActionController::Caching,
ActionController::Caching::Fragments,
ActionController::Caching::ConfigMethods,
ActionController::Caching::Pages,
ActionController::Caching::Actions,
ActionController::ConditionalGet,
ActionController::Head,
ActionController::Renderers::All,
ActionController::Renderers,
ActionController::Rendering,
ActionController::Redirecting,
ActionController::RackDelegation,
ActiveSupport::Benchmarkable,
AbstractController::Logger,
ActionController::UrlFor,
AbstractController::UrlFor,
ActionDispatch::Routing::UrlFor,
ActionDispatch::Routing::PolymorphicRoutes,
ActionController::HideActions,
ActionController::Helpers,
AbstractController::Helpers,
AbstractController::AssetPaths,
AbstractController::Translation,
AbstractController::Layouts,
AbstractController::Rendering,
AbstractController::ViewPaths,
ActionController::Metal,
AbstractController::Base,
ActiveSupport::Configurable,
Object,
ActiveSupport::Dependencies::Loadable,
Mongoid::Extensions::Object::Yoda,
Mongoid::Extensions::Object::Substitutable,
Mongoid::Extensions::Object::Reflections,
Mongoid::Extensions::Object::DeepCopy,
Mongoid::Extensions::Object::Checks,
JSON::Ext::Generator::GeneratorMethods::Object,
PP::ObjectMixin,
Kernel,
BasicObject


<Module:0x007ff271221e40>,
ActionDispatch::Routing::Helpers,
#<Module:0x007ff2714ad268>,
ActionController::Base,
ActionDispatch::Routing::RouteSet::MountedHelpers,
HasScope,
ActionController::Compatibility,
ActionController::ParamsWrapper,
ActionController::Instrumentation,
ActionController::Rescue,
ActiveSupport::Rescuable,
ActionController::HttpAuthentication::Token::ControllerMethods,
ActionController::HttpAuthentication::Digest::ControllerMethods,
ActionController::HttpAuthentication::Basic::ControllerMethods,
ActionController::RecordIdentifier, #<Module:0x007f9211d5cd70>,
ActionController::DataStreaming, ActionDispatch::Routing::Helpers,
ActionController::Streaming, #<Module:0x007f9211f7b5e8>,
ActionController::ForceSSL, ActionController::API,
ActionController::RequestForgeryProtection, ActiveRecord::Railties::ControllerRuntime,
AbstractController::Callbacks, ActionDispatch::Routing::RouteSet::MountedHelpers,
ActiveSupport::Callbacks, ActionController::Instrumentation,
ActionController::Flash, ActionController::Rescue,
ActionController::Cookies, ActiveSupport::Rescuable,
ActionController::MimeResponds, ActionController::DataStreaming,
ActionController::ImplicitRender, ActionController::ForceSSL,
ActionController::Caching, AbstractController::Callbacks,
ActionController::Caching::Fragments, ActiveSupport::Callbacks,
ActionController::Caching::ConfigMethods, ActionController::ConditionalGet,
ActionController::Caching::Pages, ActionController::Head,
ActionController::Caching::Actions, ActionController::Renderers::All,
ActionController::ConditionalGet, ActionController::Renderers,
ActionController::Head, ActionController::Rendering,
ActionController::Renderers::All, AbstractController::Rendering,
ActionController::Renderers, AbstractController::ViewPaths,
ActionController::Rendering, ActionController::Redirecting,
ActionController::Redirecting, ActionController::RackDelegation,
ActionController::RackDelegation, ActiveSupport::Benchmarkable,
ActiveSupport::Benchmarkable, AbstractController::Logger,
AbstractController::Logger, ActionController::UrlFor,
ActionController::UrlFor, AbstractController::UrlFor,
AbstractController::UrlFor, ActionDispatch::Routing::UrlFor,
ActionDispatch::Routing::UrlFor, ActionDispatch::Routing::PolymorphicRoutes,
ActionDispatch::Routing::PolymorphicRoutes, ActionController::HideActions,
ActionController::HideActions, ActionController::Metal,
ActionController::Helpers, AbstractController::Base,
AbstractController::Helpers, ActiveSupport::Configurable,
AbstractController::AssetPaths, Object,
AbstractController::Translation, JSON::Ext::Generator::GeneratorMethods::Object,
AbstractController::Layouts, ActiveSupport::Dependencies::Loadable,
AbstractController::Rendering, PP::ObjectMixin,
AbstractController::ViewPaths, Kernel,
ActionController::Metal, BasicObject
AbstractController::Base,
ActiveSupport::Configurable,
Object,
ActiveSupport::Dependencies::Loadable,
Mongoid::Extensions::Object::Yoda,
Mongoid::Extensions::Object::Substitutable,
Mongoid::Extensions::Object::Reflections,
Mongoid::Extensions::Object::DeepCopy,
Mongoid::Extensions::Object::Checks,
JSON::Ext::Generator::GeneratorMethods::Object,
PP::ObjectMixin,
Kernel,
BasicObject


use ActionDispatch::Static
use Rack::Lock
use
#<ActiveSupport::Cache::Strategy::Loc
alCache::Middleware:0x007fd3b32928c0>
use Rack::Runtime
use Rack::MethodOverride
use ActionDispatch::RequestId
use Rails::Rack::Logger
use ActionDispatch::ShowExceptions
use ActionDispatch::DebugExceptions
use ActionDispatch::RemoteIp
use ActionDispatch::Reloader
use ActionDispatch::Callbacks
use ActionDispatch::Cookies
use
ActionDispatch::Session::CookieStore
use ActionDispatch::Flash
use ActionDispatch::ParamsParser
use ActionDispatch::Head
use Rack::ConditionalGet
use Rack::ETag
use
ActionDispatch::BestStandardsSupport
use
Rack::Mongoid::Middleware::IdentityMa
p


use ActionDispatch::Static
use Rack::Lock
use
#<ActiveSupport::Cache::Strategy::Loc use ActionDispatch::Static
alCache::Middleware:0x007fd3b32928c0> use Rack::Lock
use Rack::Runtime use
use Rack::MethodOverride #<ActiveSupport::Cache::Strategy::LocalCac
use ActionDispatch::RequestId he::Middleware:0x007fe74448cf50>
use Rails::Rack::Logger use Rack::Runtime
use ActionDispatch::ShowExceptions use ActionDispatch::RequestId
use ActionDispatch::DebugExceptions use Rails::Rack::Logger
use ActionDispatch::RemoteIp use ActionDispatch::ShowExceptions
use ActionDispatch::Reloader use ActionDispatch::DebugExceptions
use ActionDispatch::Callbacks use ActionDispatch::RemoteIp
use ActionDispatch::Cookies use ActionDispatch::Reloader
use use ActionDispatch::Callbacks
ActionDispatch::Session::CookieStore use
use ActionDispatch::Flash ActiveRecord::ConnectionAdapters::Connecti
use ActionDispatch::ParamsParser onManagement
use ActionDispatch::Head use ActiveRecord::QueryCache
use Rack::ConditionalGet use ActionDispatch::ParamsParser
use Rack::ETag use ActionDispatch::Head
use use Rack::ConditionalGet
ActionDispatch::BestStandardsSupport use Rack::ETag
use
Rack::Mongoid::Middleware::IdentityMa
p


Gracias!

Preguntas?
Edwin Cruz
edwin@crowdint.com
@softr8


Designing APIs with Ruby

Recomendados

Mais conteúdo relacionado

Semelhante a Designing APIs with Ruby

Semelhante a Designing APIs with Ruby (20)

Mais de Software Guru

Mais de Software Guru (20)

Último

Último (20)

Designing APIs with Ruby