Describing Your World with Seahorse

So you've just added a suite of RESTful APIs to your web service. Now you need to generate documentation and build Ruby, Python, and JavaScript clients to consume those new APIs. With so many moving parts, how do you keep your service, documentation and clients in sync?

We all know how to describe data using ActiveRecord models. Have you considered using a model to describe your service?
A service model provides a number of benefits including: easy to generate API documentation, consistent server side parameter validation, versioned APIs, easy to build clients, and more. It also represents a unified view of your API which helps to keep your code and documentation DRY. But what does a service model look like? For instance, did you know that your APIs can be described using just four parameter types? What if your could express your APIs using a Rails DSL?

This talk will introduce Seahorse, a DSL for describing API operations for just about any web service. It provides all of the above functionality, allowing you to describe your service model in a single place with Ruby code. We will demonstrate how to use Seahorse to generate clients, model existing real-world APIs, and even build one of our own.

Given at RailsConf 2013.

Transcript

1. Describing  Your   World  with  Seahorse   RailsConf  2013   @trevorrowe  
3. gem  install  aws-­‐sdk   npm  install  aws-­‐sdk  
5. Lets  talk  about  …   APIs  
7. MonoRail*   Breaking  Apart  the  
8. API  plaform*   Rails  as  an   *  Official  uninten:onal  theme  of  RailsConf  2013  
9. APIs  should   be  EnGGes   (not  side-­‐effects)  
10. Models,  Views,  Controllers,  Oh  My!  
13. “The  shape  of  your  API  should  be   driven  by  your  Domain  model,  not  your   persistence  model.”   -­‐  Some  guy  at  RailsConf  
14. Why  You  “Need”  an  API  Model   •  Filter  incoming  parameters   •  Perform  parameter  type  conversion   •  Generate  comprehensive  API   documenta:on   •  Generate  clients   •  Versioning    
15. Describing  Your  World  with  Seahorse   •  Seahorse  describes  the  “shape”  of  a  web   service  API   •  It  does  not  describe  the  protocol   •  Extracted  from  our  work  on  building  AWS   clients  in  mul:ple  languages   –  PHP   –  Python   –  JavaScript   –  Ruby  
16. Q:  What  does  Rails  provide  to  help   me  build  API  models?   A:  Not  much  
18. *  Introduced  in  Rails  3.1  
19. Whitelisted  AXributes     •  Not  type  aware     •  Doesn’t  support  mul:ple  configura:ons   •  Ugly  to  use  with  nested_attrbiutes_for    
20. h\p://draken413o.deviantart.com/art/To-­‐the-­‐rescue-­‐121441303  
22. Strong  Parameters   Strong  Stronger  Parameters   Strong  Weak  Parameters  
23. Seahorse  Types   • Complex  Types   • Scalar  Types   • Type  metadata  
24. Structures  
25. Lists  
26. Maps  
27. •  String   •  Integer   •  Float   •  DateTime   •  Boolean   •  Blob   Scalar  Types  
28. •  Documenta:on   •  Valida:on   – Required   – Min/max  length   – Regex  pa\erns   – Enum   •  HTTP  binding   Type  Metadata  
29. Why  You  “Need”  an  API  Model   •  Filter  incoming  parameters   •  Perform  parameter  type  conversion   •  Generate  comprehensive  API  documenta:on   •  Generate  clients   •  Versioning    
30. Why  You  “Need”  an  API  Model   •  Filter  incoming  parameters   •  Perform  parameter  type  conversion   •  Generate  comprehensive  API   documentaGon   •  Generate  clients   •  Versioning    
31. Why  You  “Need”  an  API  Model   •  Filter  incoming  parameters   •  Perform  parameter  type  conversion   •  Generate  comprehensive  API  documenta:on   • Generate  clients   •  Versioning    
32. Why  You  “Need”  an  API  Model   •  Filter  incoming  parameters   •  Perform  parameter  type  conversion   •  Generate  comprehensive  API  documenta:on   •  Generate  clients   •  Versioning    
34. EnumeraGon  and  PaginaGon   •  Opera:on  level  metadata   •  Describe  what  the  interes:ng  bits  are  to   enumerate   •  Describes  how  to  “get  more”  
35. Resource  “Waiters”   •  Common  problem  for  web  services  to  be   eventually  consistent   •  Describe  what  state  is  desired   •  Describe  failure  states   •  Poll  for  resource  states  
36. Strongly  Typed  Clients   •  Create  Ruby  Struct  classes  for  each  type   •  Faster  than  hash  based  access   •  Gives  be\er  feedback  on  invalid  keys   •  Easier  to  document  
37. Configurable  Retry  Logic   •  Pluggable  retry  handler   •  Improve  clients  reliability  
38. Where  Can  I  get  Seahorse?       h\ps://github.com/awslabs/seahorse   gem  install  seahorse  
39. API  Models,  Not  a  Novel  Concept*   •  Rails  Specific   –  Grape   –  Rails::api   –  Rocket  pants   •  Others   –  Rest.li   –  Apache  Thrib   –  Swagger   *  Same  same,  but  different   *  Why  aren’t  you  using  one?  
40. @trevorrowe  
41.       hXp://aws.amazon.com/tools-­‐jobs