The document discusses best practices for designing APIs, including using RESTful design with resources, separating the API into versions and modules, implementing authentication and authorization, and handling exceptions, caching, logging, instrumentation and performance. It also covers JSON formatting, CRUD operations, pagination, and documentation.

1. Daniel Doubrovkine / Art.sy
dblock@dblock.org @dblockdotorg

2. Solid API or Else …
http://www.youtube.com/watch?v=l9vYE7B1_PU

3. The Rails Way: M(V)C
config/routes.rb
resources :artists
app/controllers/artists_controller.rb
class ArtistsController < ApplicationController
def index
@artists = …
# all kinds of stuff that serves views
respond_to do |format|
format.html { @artists }
format.json { render json: @artists.as_json }
end
end
End

4. The Rails Way: MVC
app/views/artists/index.json.erb
-@artists.each do |artist|
{
'first_name': '<%= @artist.first_name.to_json %>',
'last_name': '<%= @artist.last_name.to_json %>'
}

5. Occupy Rails?
» Where does the API start and end?
» How are we going to build API v2 on top of v1?
» Is API testing the same as controller testing?
» How much discipline are we going to need to keep sanity?
» How will deal with more difficult problems?
Caching, authentication, authorization …

6. Modern Web Applications: NoRails
» MVC UI
» RESTful API
» Storage

7. Grape
» API DSL class API < Grape::API
version „1'
rack-based / middleware
http://github.com/intridea/grape
namespace :artist
get “:id” do
Artist.find(params[:id]).as_json
end
end
namespace :artists do
get “/” do
Artist.all.as_json
end
end
end

8. Documentation
» Developers Have the Attention Span of a Fish *
* when reading documentation
» Written in Markdown
http://code.dblock.org/rendering-markdown-documents-in-rails
» Reference will be Generated
» API Sandboxes
https://github.com/mmcnierney14/API-Sandbox
» API Explorer
https://github.com/mmcnierney14/API-Sandbox

9. Testing an API
# spec/spec_helper.rb
RSpec.configure do |config|
config.include RSpec::Rails::RequestExampleGroup,
:type => :request,
:example_group => {
:file_path => /spec/api/
}
end
See “Writing Tests” @ https://github.com/intridea/grape

10. Mocking is for Java Programmers
describe "artworks" do
before(:each) do
login_as Fabricate(:admin)
end
describe "GET /api/v1/artwork/:slug" do
it "returns an unpublished artwork" do
artwork = Fabricate(:artwork, published: false)
get "/api/v1/artwork/#{artwork.slug}"
response.status.should == 200
response.body.at_json_path(“id”).should == artwork.slug # Pathy!
end
end
end
end

11. Version 1 Births Version 2
» Include Api_v1
» Folder-Driven Development (FDD)
api/api_v1/…
module Api_v1 module Api_v2
version 'v1„ version 'v2„
module Api_v1_Me module Api_v1_Me
module Api_v1_Artworks module Api_v2_Artworks
# ... # ...
end end
See “Modularizing Grape API” @ http://code.dblock.org/modularizing-a-ror-grape-api-multiple-versions

12. Exceptions Abort Flow
» Don’t question yourself, raise a hand.
rescue_from :all, :backtrace => true
error_format :json
rescue_from Mongoid::Errors::Validations do |e|
rack_response({ :message => e.message,
:detail => e.document.errors,
:backtrace => e.backtrace }.to_json)
end
end
See “Grape: trapping all exceptions within the API” @ http://code.dblock.org/grape-trapping-all-exceptions-within-the-api

13. Authentication Methods
» XApp: Exchange client ID for an XApp token
api/v1/api_xapp_auth.rb
» OAuth 2.0: Browser-Based Redirects
controllers/oauth_controller.rb
» XAuth: Exchange credentials for an OAuth token
controllers/oauth_controller.rb
» Forms Login to Website
devise/warden via user.rb
See “Grape: API Authentication w/ Devise” @ http://code.dblock.org/grape-api-authentication-w-devise

14. Authenticated Users
» Unauthenticated Calls
» Authorized Apps
» Logged In Users, RBAC
def authenticated_user
authenticated
error!('Unauthorized', 401) unless current_user
end

15. Object Identity
» Everything has an ID
» Internal ID: BSON ObjectId
» External ID: humanly-readable ID
» ID is the same for all API consumers
» API consumers know of a single ID
» When do I use a Slug?
» When do I use BSON ObjectId?

16. JSON Formats
» ActiveRecord as_json passes options recursively
:all – all fields visible to the object’s owner
:public – all fields visible to a user with :read permissions
:short – enough fields visible to a user with :read permissions, used within a collection
» JSON data can be grown incrementally

17. POST and PUT
» Validate Input Parameters in Models
save(hashie)
valid_hash_fields :first, :last

18. Authorization
» Admins have :create, :read, :update, :delete on everything, also
known as :manage
» Partners have :manage on their partner data
eg. partner location, get :all JSON
» Users have :manage on their personal data
eg. my collection, get :all JSON
» Everyone has :read on public data
eg. a published artwork, get :public JSON

19. Authorization Usage
» Implemented w/ CanCan
cannot :read, Artwork
can :read, Artwork do |artwork|
artwork.published
end
error!(„Unauthorized', 403) unless
current_user.has_authorization_to?(:delete, artist)

20. Pagination
» paginate(collection)
» :offset or :page
» :size
Pagination Helper for Grape @ https://gist.github.com/1335242

21. Logging
» Implemented as Rack Middleware
» Logs API Calls

22. Caching
» Implemented w/Rails Cache / Memcached
» Key based on Class and Identity
» Cache Locally
» Invalidate Aggressively

23. Cache Busting
» IE9
See “IE9: Cache-Busting with Grape Middleware” @
http://code.dblock.org/ie9-cache-busting-with-grape-middleware

24. Instrumentation
» See API Stats in New Relic
config/initializers/new_relic_agent_instrumentation_api.rb
See “New Relic: Performance Instrumentaiton w/ Grape” @
http://code.dblock.org/new-relic-performance-instrumentation-with-grape-api

25. Performance
» Trends

26. Next
» Deep Data
» Caching in JSON
» Generated Documentation

27. How to design a good API and why it matters (Joshua Bloch)
http://www.youtube.com/watch?v=aAb7hSCtvGw
1. Do one thing well
2. API is a Language, names matter
3. Documentation matters
4. Minimize mutability
5. Don’t make the client do anything the API could do