HTTP & Stuff

Slides from my talk on HTTP APIs given at the joint MadRailers/MadJS meetup.

Transcript

1. Mad-Railers 2014-03-31 HTTP & Stuff
2. API methods have certain characteristics (waves hands) Easier to develop against an API when these are explicit Can either make them explicit in the transport or in the messages Premise
3. require 'sinatra' ! get '/' do [ 200, # status {}, # headers '' # body ] end
4. HTTP/1.1
5. GET POST
 PUT PATCH DELETE
6. Make Safety Explicit
7. GET POST
 PUT PATCH DELETE Safe!
8. GET POST
 PUT PATCH DELETE Idempotent!
9. GET POST
 PUT PATCH DELETE Non-Idempotent!
10. Make Safety Explicit
11. Make Success/Failure Obvious
12. 1XX Informational 2XX Success
 3XX Redirection 4XX Client Error 5XX Server Error
13. Save Bandwidth
14. curl -H “If-None-Match: 5d41402abc4b2a76b9719d911017c592" \ http://example.com
15. curl -H "Accept-Encoding: gzip" http://example.com
16. Agree on Message Format
17. curl -H "Accept: application/vnd.example+json;version=1" \ http://example.com
18. require 'sinatra' ! get '/' do [ 200, # status {}, # headers '' # body ] end
19. Hypermedia
20. { "items": [{ "0": 1, "1": "apache2", "2": "2014-02-23T13:23:47Z" }, { "0": 2, "1": "apt", "2": "2013-10-10T17:01:03Z" }] }
21. { "cookbooks": [{ "id": 1, "name": "apache2", "last_modified": "2014-02-23T13:23:47Z" }, { "id": 2, "name": "apt", "last_modified": "2013-10-10T17:01:03Z" }] }
22. { "cookbooks": [{ "id": 1, "name": "apache2", "last_modified": "2014-02-23T13:23:47Z", "_links": { "unshare": "/cookbooks/apache2", "self": "/cookbooks/apache2" } }, { "id": 2, "name": "apt", "last_modified": "2013-10-10T17:01:03Z", "_links": { "self": "/cookbooks/apt" } }], "_links": { "share": "/cookbooks", "self": "/cookbooks", "search": "/cookbooks/search{?q,items,start}" } }
23. HATEOAS
24. Purpose + State Machine
25. Hypermedia
26. In Ruby/On Rails
27. Chef Supermarket
28. curl -H "If-None-Match: \"b32d02c99beb516ba326ae25801b566b\"" \ http://community.opscode.com/api/v1/cookbooks?items=1
29. Supermarket::Application.routes.draw do namespace :api, defaults: { format: :json } do namespace :v1 do get 'cookbooks' => 'cookbooks#index' get 'search' => 'cookbooks#search' get 'cookbooks/:cookbook' => 'cookbooks#show', as: :cookbook get 'cookbooks/:cookbook/versions/:version' => 'cookbook_versions#show', as: :cookbook_version post 'cookbooks' => 'cookbook_uploads#create' delete 'cookbooks/:cookbook' => 'cookbooks#destroy' end end end
30. { "error_code": "NOT_FOUND", "error_messages": [ "Resource does not exist" ] }
31. Domain Specificity
32. List, Search, Show, Download, Share, Unshare
33. Pushing towards HATEOAS on Rails
34. diff --git a/Gemfile b/Gemfile index 03c243b..cde0a05 100644 --- a/Gemfile +++ b/Gemfile @@ -17,6 +17,7 @@ gem 'paperclip' gem 'virtus', require: false gem 'kaminari' +gem 'api-versions' gem 'sentry-raven', github: 'getsentry/raven-ruby' gem 'statsd-ruby', require: 'statsd'
35. Supermarket::Application.routes.draw do api vendor_string: 'supermarket', default_version: 1 do version 1 do scope 'v1' do # routes for application/vnd.supermarket+json;version=1 end end end ! namespace :api, defaults: { format: :json } do namespace :v1 do # existing routes end end end
36. json.start @start json.total @total json.items @cookbooks do |cookbook| json.cookbook_name cookbook.name json.cookbook_maintainer cookbook.maintainer json.cookbook_description cookbook.description json.cookbook api_v1_cookbook_url(cookbook) end https://github.com/rails/jbuilder
37. class CookbookSerializer < ActiveModel::Serializer attributes :name, :description has_one :maintainer end https://github.com/rails-api/active_model_serializers
38. https://github.com/apotonick/roar class CookbookRepresenter < Roar::Decorator include Roar::Representer::JSON ! property :name property :description ! link :self do api_v1_cookbook_url(represented) end ! collection :cookbook_versions, class: CookbookVersion do property :version property :license ! link :self do api_v1_cookbook_url(represented.cookbook, represented) end ! link :artifact do represented.tarball.url end end end
39. collection :@cookbooks attributes :name, :description child(:maintainer) { attributes :username } https://github.com/ccocchi/rabl-rails
40. require 'oat/adapters/json_api' ! class CookbookSerializer < Oat::Serializer adapter Oat::Adapters::JsonAPI ! schema do type "cookbook" link :self, href: api_v1_cookbook_url(item) ! properties do |props| map_properties :name, :description ! entities :cookbook_versions, item.cookbook_versions, CookbookVersionSerializer end end end https://github.com/ismasan/oat
41. require 'addressable/template' ! def search_template_url(params = {}) Addressable::Template.new( Addressable::URI.join( api_v1_cookbooks_search_url, '{?q,items,start}' ) ).expand(params) end https://github.com/sporkmonger/addressable
42. Building Hypermedia APIs with HTML5 and Node Mike Amundsen
43. Designing Hypermedia APIs Steve Klabnik
44. Thanks! https://pinboard.in/u:bcobb/t:madrailers2014-03-31