Building an API in Rails without Realizing It

Rails APIsMonday, February 25, 13

@markbates

Monday, February 25, 13

http://www.metacasts.tv

CONFOO2013




Rails APIsMonday, February 25, 13

Rails APIsWeb


you’re probably doing it wrong


Don’t Panic!


most APIs are an after thought


we can prevent that!


3 simple rules for building an API


1. consume your own API


2. document your API


3. version your API


building the API


SOAMonday, February 25, 13

Service Oriented Architecture


SOA Pros


SOA Pros

• Scales Easily


SOA Pros

• Scales Easily

• Separate Concerns/Very Clean


SOA Pros

• Scales Easily


• Can be easier to maintain


SOA Pros

• Scales Easily



• Solid Architecture


SOA Pros

• Scales Easily



• Solid Architecture

• Easier to refactor/rebuild


SOA Cons


SOA Cons

• Can be more difficult to maintain


SOA Cons


• More complex deploys


SOA Cons



• Managing several applications


SOA Cons




• Potential for ‘out-of-sync’ apps


SOA Cons




• Potential for ‘out-of-sync’ apps

• More difficult to test integration


API Client


API

Client

Client


API Client

Client

Client


Client

Client

Client

Service 1

Service 2

Service 3


a quick detour


Rails encourages poor API design!


class TodosController < ApplicationController # GET /todos # GET /todos.json def index @todos = Todo.all respond_to do |format| format.html # index.html.erb format.json { render json: @todos } end end # GET /todos/1 # GET /todos/1.json def show @todo = Todo.find(params[:id]) respond_to do |format| format.html # show.html.erb format.json { render json: @todo } end end # GET /todos/new # GET /todos/new.json def new @todo = Todo.new respond_to do |format| format.html # new.html.erb format.json { render json: @todo } end end # GET /todos/1/edit def edit @todo = Todo.find(params[:id]) end

# POST /todos # POST /todos.json def create @todo = Todo.new(params[:todo]) respond_to do |format| if @todo.save format.html { redirect_to @todo, notice: 'Todo was successfully created.' } format.json { render json: @todo, status: :created, location: @todo } else format.html { render action: "new" } format.json { render json: @todo.errors, status: :unprocessable_entity } end end end # PUT /todos/1 # PUT /todos/1.json def update @todo = Todo.find(params[:id]) respond_to do |format| if @todo.update_attributes(params[:todo]) format.html { redirect_to @todo, notice: 'Todo was successfully updated.' } format.json { head :no_content } else format.html { render action: "edit" } format.json { render json: @todo.errors, status: :unprocessable_entity } end end end # DELETE /todos/1 # DELETE /todos/1.json def destroy @todo = Todo.find(params[:id]) @todo.destroy respond_to do |format| format.html { redirect_to todos_url } format.json { head :no_content } end endend


Don’t Scaffold!


class TodosController < ApplicationController def index @todos = Todo.all end def show @todo = Todo.find(params[:id]) end def new @todo = Todo.new end def edit @todo = Todo.find(params[:id]) end def create @todo = Todo.new(params[:todo]) if @todo.save redirect_to @todo, notice: 'Todo was successfully created.' else render action: "new" end end def update @todo = Todo.find(params[:id]) if @todo.update_attributes(params[:todo]) redirect_to @todo, notice: 'Todo was successfully updated.' else render action: "edit" end end def destroy @todo = Todo.find(params[:id]) @todo.destroy redirect_to todos_path, notice: 'Todo was successfully destroyed.' endend


class TodosController < ApplicationController inherit_resourcesend


https://github.com/josevalim/inherited_resources

Inherited Resources


class Api::V1::TodosController < ApplicationController respond_to :json before_filter do request.format = :json end def index @todos = Todo.all respond_with @todos end def show @todo = Todo.find(params[:id]) respond_with @todo end def create @todo = Todo.new(params[:todo]) if @todo.save respond_with @todo else render json: @todo.errors, status: :unprocessable_entity end end def update @todo = Todo.find(params[:id]) if @todo.update_attributes(params[:todo]) respond_with @todo else render json: @todo.errors, status: :unprocessable_entity end end def destroy @todo = Todo.find(params[:id]) @todo.destroy head :no_content endend


Api::V1::TodosController

version your API!

/api/v1/todos


i prefer URL versioning


others prefer header versioning


just pick one and stick with it!


SOA Review


SOA Review

• We’ve cleaned up our code


SOA Review


• We know the API Works


SOA Review


• We know the API Works

• We’re now in a good place to scale


consuming the API


don’t use Rails views


JavaScript


CORSMonday, February 25, 13

Cross-origin Resource Sharing


https://github.com/cyu/rack-cors

rack-cors


module YourApp class Application < Rails::Application # ... config.middleware.use Rack::Cors do allow do origins '*' resource '*', headers: :any, methods: [:get, :post, :put, :delete, :options] end end end


JavaScript Pros


JavaScript Pros

• Scales Easily/Pushes processing to client side


JavaScript Pros




JavaScript Pros




• “Responsive/Native” feel for clients


JavaScript Pros




• “Responsive/Native” feel for clients

• Easily consumes your API


JavaScript Cons


JavaScript Cons• Can be more difficult to maintain



• Multiple languages (backend/front-end)




• Difficult to test integration





• JavaScript





• JavaScript

• Paradigm shift in architecture





• JavaScript


• Accessibility issues





• JavaScript



• SEO concerns





• JavaScript



• SEO concerns

• !!Internet Explorer!!


pick a framework


don’t just use jQuery


the big three


Backbone.js

http://backbonejs.org/


ember

http://emberjs.com/


Angular.js

http://angularjs.org/


i can’t use JavaScript


2 approaches


“compiled” sites


build your own API library (and open source it!)


class TodosController < ApplicationController def index @todos = ApiLib::Todo.all end def show @todo = ApiLib::Todo.find(params[:id]) end def new @todo = ApiLib::Todo.new end def edit @todo = ApiLib::Todo.find(params[:id]) end def create @todo = ApiLib::Todo.new(params[:todo]) if @todo.save redirect_to @todo, notice: 'Todo was successfully created.' else render action: "new" end end def update @todo = ApiLib::Todo.find(params[:id]) if @todo.update_attributes(params[:todo]) redirect_to @todo, notice: 'Todo was successfully updated.' else render action: "edit" end end def destroy @todo = ApiLib::Todo.find(params[:id]) @todo.destroy redirect_to todos_path, notice: 'Todo was successfully destroyed.' endend


hey! there is duplicate* code

now


is there? or did we just move it

around?


Todo became ApiLib::Todo


we now have a reference

implementation


make sure to cache!!


The HackMonday, February 25, 13

Please don’t do this!


I’m Serious.


Don’t use this hack!


I probably shouldn’t even show you it.


Ok, I’ll show you, but don’t tell

people where you heard it.


class TodosController < ApplicationController def index res = Api::V1::TodosController.action(:index).call(env) @todos = JSON.parse(res[2].body).map do |data| OpenStruct.new(data) end end end


projects worth noting


rails-apiMonday, February 25, 13

api_docMonday, February 25, 13

Final Thoughts


Final Thoughts

• Consume your API


Final Thoughts


• Version your API


Final Thoughts



• Document your API


Final Thoughts



• Document your API

• Did I mention consume your own API?



CONFOO2013

Thank You

@markbates




Building an API in Rails without Realizing It

Technology

Transcript of Building an API in Rails without Realizing It