Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Qype API - Lessons learned

Qype API - Lessons learned

For Hamburg OnRuby and Hamburg Mobile DevCamp. A retrospective on building the Qype service API and lessons learned.

Matthias Käppler

August 04, 2012

More Decks by Matthias Käppler

Other Decks in Technology


  1. Qype  API:  Lessons  Learned   A  retrospec3ve  on  REST-­‐ful  API

     design     July  2012   MaDhias  Käppler   Qype  GmbH  
  2. A  brief  history...   •  Qype’s  API  is  deployed  as

     a  RoR  2.3  app   •  Online  since  end  of  2008   •  Primary  purpose  was  serving  the  iOS  app   •  Strictly  REST-­‐ful,  small  feature  set     GET http://api.qype.com/v1/places/1
  3. Architecture   DB   SOLR   API  app   Model

      Mappings   Controllers   Website  app   AR  Models   Search   Logic   Search   Logic   SOLR  Ruby  bindings   Serializers  
  4. Today   •  Load  ~60M  req/month   •  ~2000  registered

     consumers   •  99%  of  traffic  caused  by  0.01%  of  consumers   •  Consumers  vastly  differ  in  requirements   •  REST  paradigm  broken  up  in  many  places  
  5. Today  (cont.)   •  Over  the  years,  complexity  grew  with

     the   requirements   – More  feature  rich  mobile  apps   – MORE  mobile  apps   – More  diverse  API  consumers   •  The  result?  
  6. Service  APIs  vs.  Websites   •  Mistakes  in  API  design

     are  not  forgiven!   – Client  lock-­‐in   •  Clients  can  differ  vastly   – Mobile  app  vs.  Web  mash-­‐up   •  Authen3ca3on  and  access  control   – An  API  is  meant  to  access  your  core  data  by  design   •  Performance  maDers  (even  more)  
  7. Versioning   •  Granularity   – service  vs  endpoint  versioning  

    •  Architecture/deployment   – One  app  per  version?   •  E.g.  qype-­‐api-­‐v2   – One  engine  per  version?   •  E.g.  app/engines/v2   – One  class  per  version?   •  E.g.  app/controllers/resource_controller_v2.rb  
  8. Versioning  (cont.)   •  Tes3ng?   – i.e.  to  which  version

     does  a  test  apply?   •  Code  sharing  vs.  code  duplica3on?   – i.e.  not  all  routes  may  change  with  an  increment   •  Also  affects  caching  etc.   •  Gems:   – hDps://github.com/bploetz/versionist   – hDps://github.com/filtersquad/rocket_pants  
  9. A  modular  architecture   Core  API   Apps  AAL  

    Partner  AAL   Standard  API   consumers   Partner  1   Partner  N   App  1   App  N  
  10. Why  REST?   •  Keeps  the  interface  lean  and  mean

      •  Shared  understanding  of  ac3ons   •  Makes  a  system  connected   •  Makes  responses  cacheable   •  It’s  SIMPLE!  
  11. But:  simple  can  be  bad!   •  Our  apps  are

     not  simple   •  Hence,  a  simple  API  is  not  always  suitable   •  REST  paradigm  can  be  sokened  on  an  AAL   – Batch  requests   – {  “requests”:  [      {  “method”:  “get”,  “uri”:  “hDp://...”  }      ...   ]  }  
  12. Resource  mapping   •  Qype  API  employs  custom  resource  mapper

      •  Goal:   – Map  AR  models  to  intermediate  format,  then   serialize   – Review.first.to_api(:hash)   •  Gems:   – hDps://github.com/rails/jbuilder/   – hDps://github.com/nesquena/rabl  
  13. Acceptance  tes3ng   •  Crea3ng  an  acceptance  test  suite  for

     a  service   API  is  not  simple   •  Recommended  for  deep  end-­‐2-­‐end  tests   •  Test  set-­‐up  /  tear-­‐down   •  RSpec  +  consumer  subjects  
  14. Documenta3on   •  Bad:  put  away  in  a  wiki  

    •  Good:  close  to  the  code   •  BeDer:  is  part  of  the  code   – Leverage  REST  representa3ons   – Self-­‐documen3ng  API  code