#WWCode Ruby Tuesday

API Design

Alicia Liu

@aliciatweet

Application Programming Interface

  • Purpose
  • Contract

Consumers

  • Mobile app
  • JavaScript
  • Developers

        -------------- GET /coders ----------->
client                                            server
        <-------- <html>...</html> ------------


        -------------- GET /coders ----------->
client                                            server (API)
        <---- {'coders':['Alice','Bob']} ------

                

REST

  • Stateless
  • Resources
  • Verbs: POST, GET, PUT, DELETE

#routes.rb

resources :coders, :only => [:create, :show, :update, :delete]

# POST /coders
# GET /coders/:id
# PUT /coders/:id
# DELETE /coders/:id
                

Payloads

  • JSON
  • Serialization
    • as_json
    • Presenters
    • RABL, Jbuilder

  # coders_controller.rb
  class CodersController < ApplicationController
    def show
      @coder = Coder.find(params[:id])

      respond_to do |format|
        format.html
        format.json { render :json => @coder.as_json }
      end
    end
  end
                

Authentication

  • Basic HTTP auth
  • Access token

Versioning


#routes.rb
namespace :api do
  namespace :v1 do
    get '/coders', :to => 'coders#index'
    get '/coders/:id', :to => 'coders#show'
  end
  namespace :v2 do
    get '/coders/:id', :to => 'coders#show'
  end
end

# GET /api/v1/coders
# GET /api/v1/coders/:id
# GET /api/v2/coders/:id
# GET /api/v2/coders => 404
            

Resources

Pun not intended