Building API Tooling that Doesn't Suck

Transcript

1. Building  API  Tooling     That  Doesn’t  Suck   A  Sco8  Feinberg  Produc<on   @sco8efein    
2. Sco8  Feinberg           Developer  Evangelist  at  WePay   @sco8efein    
3. Today’s  Agenda   @sco8efein    
4. What  is  good  API  Tooling?     How  do  I  build  good,  scalable   API  tooling?   @sco8efein    
5. What  is  API  Tooling?     @sco8efein    
6. @sco8efein    
7. Documenta<on   1.  Tutorials   2.  Reference  Docs   3.  Explana<on/Use  Cases   @sco8efein    
8. Tutorials   @sco8efein    
9. Explain  what  you’re  accomplishing   Detailed  Steps   Copy/Paste  Code  Examples   @sco8efein    
11. Offer  High  Level  Steps   Don’t  waste  my  9me   @sco8efein    
13. Reference  Docs   @sco8efein    
14. @sco8efein    
15. @sco8efein    
17. Document  every  resource   structure     Visual  Duplica<on  is  OK-­‐ don’t  make  me  jump  around  
18. Document  every  API   Request  +  Response     Explana<ons  and  examples   for  each  parameter  
19. Building  Documenta<on   @sco8efein    
20. Create  an  API  Spec   @sco8efein    
21. RAMLSpec   Made  up  of  YAML,   JSON,  and  Markdown   @sco8efein    
22. JSONSchema   @sco8efein    
23. Swagger  2.0   @sco8efein    
24. API  Blueprint  
25. Genera<ng  a  Spec  
26. Genera<ng  a  Spec   @sco8efein    
27. Par<ally  Code  Generated  Spec   Generate  +  Update  Code-­‐Level   Parts  of  the  Spec     Leave  Blanks  for  Documenta<on   Fields   @sco8efein    
28. Grape  to  Swagger       w/  grape-­‐swagger     Rails  Serializers  to  Swagger     w/Swaggard     @sco8efein    
29. Hand-­‐Built  Specs   Workflow:  Add  a  new  resource,  commit  a  new   spec  for  it     CLI  Tools:   •  Scaffolding   •  Concatena<ng  Files   •  Valida<on   @sco8efein    
30. documenta<on-­‐generator  -­‐r  ki8en     Created  raml_specs/ki8en.raml   Created  markdown_documenta<on/ki8en.markdown   Created  schemas/ki8en_request.json   Created  schemas/ki8en_response.json   Created  examples/ki8en.json   @sco8efein    
31. From  Specs  to  Docs   @sco8efein    
33. @sco8efein    
34. @sco8efein    
36. Spec  -­‐>  SDKs   h8ps://github.com/swagger-­‐api/swagger-­‐ codegen   h8ps://apima<c.io/   h8ps://github.com/mulesof/raml-­‐client-­‐ generator   h8p://restunited.com/   h8ps://github.com/interagent/heroics   @sco8efein    
37. Takeaways   •  Have  an  API  Spec   •  Build  tooling  around  your  documenta<on,  spec   genera<on,  etc  to  minimize  duplicated  effort  and   keep  everything  up  to  date   •  For  your  CLI  tool  genera<on:  h8ps://github.com/ codegangsta/cli   •  Good  API  Tools  that  scale  allow  you  to-­‐   –  Update  API  endpoints  faster   –  Keep  everything  consistent   –  Decrease  maintenance  effort   @sco8efein    
38. Ques<ons?   Follow  Me  on  Twi8er  @sco8efein