En esta platica trate de transmitir mejores practicas que se deben tener en cuenta cuando se diseña una API, y como ruby on rails te podria ayudar a desarrollarla en muy poco tiempo

1. Diseño de APIs con Ruby
Edwin Cruz @softr8

2. PLAN
• Que es una API
• Como implementar una buena API
• Usando Ruby on Rails para implementar una
API
• Patrones de diseño

3. “ Application
Programming
Interface
“

4. API
Es una manera para
comunicar dos
aplicaciones entre ellas.

5. TIPOS DE API
• Library
• SDK
• Web services

6. PRIMERAS API - SOAP
Simple
Object
Access
Protocol

7. REST
REpresentation
State
Transfer

8. REQUISITOS REST

9. REQUISITOS REST
Separación de responsabilidades

10. REQUISITOS REST
Separación de responsabilidades
Cliente/Servidor

11. REQUISITOS REST
Separación de responsabilidades
Cliente/Servidor
Sin estado

12. REQUISITOS REST
Separación de responsabilidades
Cliente/Servidor
Sin estado
Puede ser “Cacheable”

13. REQUISITOS REST
Separación de responsabilidades
Cliente/Servidor
Sin estado
Puede ser “Cacheable”
Sistema a capas

14. REQUISITOS REST
Separación de responsabilidades
Cliente/Servidor
Sin estado
Puede ser “Cacheable”
Sistema a capas
Interface uniforme

15. CRUD
Create Altas
Read Bajas
Update Cambios
Delete Consultas

16. REST + CRUD

17. REST + CRUD
Recursos a través de URLs únicas
Usando correctamente los verbos HTTP

18. RECURSO

19. RECURSO
Cualquier accion expuesta a travez de un servidor
web

20. RECURSO
Cualquier accion expuesta a travez de un servidor
web
Tienen una representación en datos

21. RECURSO
Cualquier accion expuesta a travez de un servidor
web
Tienen una representación en datos
Con un servicio web intercambiamos
representaciones de recursos

22. REST-ISH + JSON

23. REST-ISH + JSON
=

24. REST-ISH + JSON
=
Cosas Increibles

25. ¿PORQUÉ UN API?

26. ¿PORQUÉ UN API?
Aumenta la flexibilidad y utilidad de tus
aplicaciones

27. ¿PORQUÉ UN API?
Aumenta la flexibilidad y utilidad de tus
aplicaciones
Proporciona valor de negocio

28. ¿PORQUÉ UN API?
Aumenta la flexibilidad y utilidad de tus
aplicaciones
Proporciona valor de negocio
Ayuda a comunicar aplicaciones entre ellas

29. ¿QUÉ
CARACTERÍSTICAS?

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

31. ¿QUÉ
CARACTERÍSTICAS?
Fácil de implementar y mantener
Buen rendimiento

32. ¿QUÉ
CARACTERÍSTICAS?
Fácil de implementar y mantener
Buen rendimiento
Escalable

33. ¿CUÁLES SON LOS
RETOS?

34. ¿CUÁLES SON LOS
RETOS?
La red es un eslabón débil, GEO localizacion de los
clientes

35. ¿CUÁLES SON LOS
RETOS?
La red es un eslabón débil, GEO localizacion de los
clientes
Administrar Cambios

36. ¿CUÁLES SON LOS
RETOS?
La red es un eslabón débil, GEO localizacion de los
clientes
Administrar Cambios
Uso indebido

37. ¿CUÁLES SON LOS
RETOS?
La red es un eslabón débil, GEO localizacion de los
clientes
Administrar Cambios
Uso indebido
Balanceo de trafico

38. ¿CUÁLES SON LOS
RETOS?
La red es un eslabón débil, GEO localizacion de los
clientes
Administrar Cambios
Uso indebido
Balanceo de trafico
Picos de uso

39. ¿CUÁLES SON LOS
RETOS?
La red es un eslabón débil, GEO localizacion de los
clientes
Administrar Cambios
Uso indebido
Balanceo de trafico
Picos de uso
Errores

40. DISEÑAR UNA BUENA
API

41. CONVENCIONES REST

42. USAR CORRECTAMENTE
VERBOS HTTP

43. REST + CRUD
GET /api/products #Listado
{"products" :
[
{"product" : { "id" : 1, "name" : "Producto 1", "status" : "archived"} },
{"product" : { "id" : 2, "name" : "Producto 2", "status" : "active" } }
]
}

44. REST + CRUD
GET /api/products/2 #Ver
{"product" : { "id" : 2, "name" : "Producto 2", "status" : "active" } }

45. REST + CRUD
POST /api/products #Crear
{
"name" : "Producto 2"
}

46. REST + CRUD
PUT /api/products/2 #Actualizar
{
"name" : "Producto dos"
}

47. REST + CRUD
DELETE /api/products/2 #Eliminar

48. VERSIONES DE LA API
• API Interna (entre aplicaciones)
• API Externa (aplicacion movil ? )
• API Usuarios (publico en general)

49. VERSIONANDO TU API
/int/api/products
/ext/api/products
/pub/api/products

50. VERSIONANDO TU API
/int/api/products?version=2
/ext/api/products?version=2
/pub/api/products?version=2

51. VERSIONANDO TU API
/v2/int/api/products
/v2/ext/api/products
/v2/pub/api/products

52. VERSIONANDO TU API
http://int.myapp.com/products
http://api.myapp.com/products

53. MUNDO IDEAL

54. MUNDO IDEAL
Uso de: Accept Header

55. MUNDO IDEAL
Uso de: Accept Header
Accept: application/vnd.mycompany.com;version=2,application/json

56. CODIGOS HTTP
200 OK
201 Created
202 Accepted
400 Bad Request
401 Unauthorized
402 Payment Required
404 Not Found
409 Conflict
422 Unprocessable Entity
500 Internal Server Error
503 Service Unavailable

57. CODIGOS HTTP
HTTP/1.1 200 ok
GET /v1/products
{"products" :
[
{"product" : { "id" : 1, "name" : "Producto 1", "status" : "archived"} },
{"product" : { "id" : 2, "name" : "Producto 2", "status" : "active" } }
]
}

58. CODIGOS HTTP
HTTP/1.1 201 Created
POST /v1/products
{
“product”: [
“name” : “name”
]
}

59. CODIGOS HTTP
HTTP/1.1 400 Bad Request
{
“errors”: [
“Estructura JSON no valida”,
“unexpected TSTRING, expected ‘}’ at
line 2”
]
}

60. CODIGOS HTTP
HTTP/1.1 401 Unauthorized
{
“errors”: [
“api_key not found”
]
}

61. CODIGOS HTTP
HTTP/1.1 401 Unauthorized
{
“errors”: [
“api_key no valida”,
“api_key no puede contener
espacios”
]
}

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

63. CODIGOS HTTP
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”
]
]
}

64. CODIGOS HTTP
HTTP/1.1 500 Internal Server Error
{
“exception”: [
“Base de datos no disponible”
]
}

65. CODIGOS HTTP
HTTP/1.1 503 Service Unavailable
{
“messages”: [
“En mantenimiento”
]
}

66. OPCIONES AVANZADAS
• Simuladores
• Autenticación
• Validadores
• Limite de uso
• Rapidez
• Balanceo

67. USANDO RUBY ON
RAILS PARA
IMLEMENTAR UNA API

68. APIS ON RAILS - REST
#config/routes.rb
MyApp::Application.routes.draw do
resources :products
end
$ rake routes
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

69. APIS ON RAILS - REST
#config/routes.rb
MyApp::Application.routes.draw do
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

70. APIS ON RAILS -
VERSIONES
gem 'versionist'
#config/routes.rb
MyApp::Application.routes.draw do
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

71. APIS ON RAILS,
CONTROLADOR
class V1::ProductsController < ApplicationController
def index
products = Product.paginate(:page => (params[:page] || 1),
:per_page => (params[:per_page] || 100)).all
render :json => products.to_json
end
def show
product = Product.find(params[:id])
render :json => product.to_json
end
def update
product = Product.find(params[:id])
product.update_attributes(params[:product])
render :json => product.to_json
end
def destroy
product = Product.find(params[:id])
head product.destroy ? :ok : :unprocessable_entity
end
end

72. APIS ON RAILS,
CONTROLADOR
class ApplicationController < ActionController::Base
rescue_from ActiveRecord::UnknownAttributeError, ArgumentError do |exception|
respond_with_error(exception, 400)
end
rescue_from ActiveRecord::RecordNotFound do |exception|
respond_with_error(exception, 404)
end
rescue_from ActiveRecord::RecordInvalid do |exception|
respond_with_error(exception, 422, errors: exception.record.errors.messages)
end
rescue_from RuntimeError do |exception|
respond_with_error(exception, 500)
end
private
def respond_with_error(exception, code, errors = {})
render json: {error: exception.class.to_s,
message: exception.to_s,
errors: errors},
status: code
end
end

73. APIS ON RAILS,
CONTROLADOR
class V2::ProductsController < ApplicationController
respond_to [:json, :xml, :html]
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 = V2::Product.find(params[:id])
@product.update_attributes(params[:product])
respond_with @product
end
def destroy
@product = V2::Product.find(params[:id])
respond_with @product.destroy
end
end

74. 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

75. APIS ON RAILS,
CONTROLADOR
gem ‘rabl’
class V3::ProductsController < ApplicationController
respond_to [:json, :xml]
def index
@products = V3::Product.paginate(:page => (params[:page] || 1),
:per_page => (params[:per_page] || 100)).all
end
def show
@product = V3::Product.find(params[:id])
end
def update
@product = V3::Product.find(params[:id])
@product.update_attributes(params[:product])
end
def destroy
@product = V3::Product.find(params[:id])
render json: {}, status: @product.destroy ? :ok : :unprocessable_entity
end
end

76. 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} ]
}
}
]
}

77. 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

78. 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

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

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

81. APIS ON RAILS
SEGURIDAD
gem ‘rabl’
class V3::ProductsController < ApplicationController
before_filter :authenticate_user!
respond_to :json, :xml
def index
@products = V3::Product.paginate(:page => (params[:page] || 1),
:per_page => (params[:per_page] || 100)).all
end
def show
@product = V3::Product.find(params[:id])
end
def update
@product = V3::Product.find(params[:id])
@product.update_attributes(params[:product])
end
def destroy
@product = V3::Product.find(params[:id])
render json: {}, status: @product.destroy ? :ok : :unprocessable_entity
end
end

82. ESCRIBIENDO PRUEBAS

83. 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

84. APIS ON RAILS
PRUEBAS
describe V3::ProductsController do
before do
@request.env["HTTP_ACCEPT"] = "application/json"
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_response = JSON.parse(response.body)
json_response['error'].should == "ActiveRecord::RecordNotFound"
json_response['message'].should == "Couldn't find Product with id=-1"
end
end
end
end

85. APIS ON RAILS
PRUEBAS
describe V3::ProductsController do
before do
@request.env["HTTP_ACCEPT"] = "application/json"
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

86. APIS ON RAILS
PRUEBAS
describe V3::ProductsController do
before do
@request.env["HTTP_ACCEPT"] = "application/json"
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

87. ROR, DEMACIADO PARA
LAS API?
• Helpers
• Vistas
• Administracion de assets
• Generadores de html
• Template engines

88. <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,
JSON::Ext::Generator::GeneratorMethods::Object,
PP::ObjectMixin,
Kernel,
BasicObject

89. <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, #<Module:0x007f9211d5cd70>,
ActionController::HttpAuthentication::Basic::ControllerMethods, ActionDispatch::Routing::Helpers,
ActionController::RecordIdentifier, #<Module:0x007f9211f7b5e8>,
ActionController::DataStreaming, ActionController::API,
ActionController::Streaming, ActiveRecord::Railties::ControllerRuntime,
ActionController::ForceSSL, ActionDispatch::Routing::RouteSet::MountedHelpers,
ActionController::RequestForgeryProtection, ActionController::Instrumentation,
AbstractController::Callbacks, ActionController::Rescue,
ActiveSupport::Callbacks, ActiveSupport::Rescuable,
ActionController::Flash, ActionController::DataStreaming,
ActionController::Cookies, ActionController::ForceSSL,
ActionController::MimeResponds, AbstractController::Callbacks,
ActionController::ImplicitRender, ActiveSupport::Callbacks,
ActionController::Caching, ActionController::ConditionalGet,
ActionController::Caching::Fragments, ActionController::Head,
ActionController::Caching::ConfigMethods, ActionController::Renderers::All,
ActionController::Caching::Pages, ActionController::Renderers,
ActionController::Caching::Actions, ActionController::Rendering,
ActionController::ConditionalGet, AbstractController::Rendering,
ActionController::Head, AbstractController::ViewPaths,
ActionController::Renderers::All, ActionController::Redirecting,
ActionController::Renderers, ActionController::RackDelegation,
ActionController::Rendering, ActiveSupport::Benchmarkable,
ActionController::Redirecting, AbstractController::Logger,
ActionController::RackDelegation, ActionController::UrlFor,
ActiveSupport::Benchmarkable, AbstractController::UrlFor,
AbstractController::Logger, ActionDispatch::Routing::UrlFor,
ActionController::UrlFor, ActionDispatch::Routing::PolymorphicRoutes,
AbstractController::UrlFor, ActionController::HideActions,
ActionDispatch::Routing::UrlFor, ActionController::Metal,
ActionDispatch::Routing::PolymorphicRoutes, AbstractController::Base,
ActionController::HideActions, ActiveSupport::Configurable,
ActionController::Helpers, Object,
AbstractController::Helpers, JSON::Ext::Generator::GeneratorMethods::Object,
AbstractController::AssetPaths, ActiveSupport::Dependencies::Loadable,
AbstractController::Translation, PP::ObjectMixin,
AbstractController::Layouts, Kernel,
AbstractController::Rendering, BasicObject
AbstractController::ViewPaths,
ActionController::Metal,
AbstractController::Base,
ActiveSupport::Configurable,
Object,
ActiveSupport::Dependencies::Loadable,
JSON::Ext::Generator::GeneratorMethods::Object,
PP::ObjectMixin,
Kernel,
BasicObject

90. RAILS A DIETA

91. RAILS A DIETA
Rails es modular

92. RAILS A DIETA
Rails es modular
Para crear APIs, algunos Middlewares no son
necesarios

93. RAILS A DIETA
Rails es modular
Para crear APIs, algunos Middlewares no son
necesarios
rails-api

94. 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

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

96. RAILS-API?
• ActiveRecord (manejo de errores)
• Validaciones (responder a varios formatos)
• Controladores, sistema de rutas (versionamiento)
• Muchas librerias(Gems)
• Autenticación (oauth, token, basic auth)
• Mismos web servers confiables (mismo hosting)

97. RAILS-API?
• REST
• CRUD

98. CONCLUSION

99. CONCLUSION
Rails es perfecto para API’s!

100. Gracias!
Preguntas?
Edwin Cruz
edwin@crowdint.com
@softr8