Building API Tooling that Doesn't Suck

Transcript

1. Building  API  Tooling    
   That  Doesn’t  Suck  
   A  Sco8  Feinberg  Produc@sco8efein    
   

   View Slide

2. Sco8  Feinberg  
    
    
    
    
   Developer  Evangelist  at  WePay  
   @sco8efein    
   

   View Slide

3. Today’s  Agenda  
   @sco8efein    
   

   View Slide

4. What  is  good  API  Tooling?  
    
   How  do  I  build  good,  scalable  
   API  tooling?  
   @sco8efein    
   

   View Slide

5. What  is  API  Tooling?  
    
   @sco8efein    
   

   View Slide

6. @sco8efein    
   

   View Slide

7. Documenta1.  Tutorials  
   2.  Reference  Docs  
   3.  Explana@sco8efein    
   

   View Slide

8. Tutorials  
   @sco8efein    
   

   View Slide

9. Explain  what  you’re  accomplishing  
   Detailed  Steps  
   Copy/Paste  Code  Examples  
   @sco8efein    
   

   View Slide

10. View Slide

11. Offer  High  Level  Steps  
    Don’t  waste  my  9me  
    @sco8efein    
    

    View Slide

12. View Slide

13. Reference  Docs  
    @sco8efein    
    

    View Slide

14. @sco8efein    
    

    View Slide

15. @sco8efein    
    

    View Slide

16. View Slide

17. Document  every  resource  
    structure  
     
    Visual  Duplicadon’t  make  me  jump  around  
    

    View Slide

18. Document  every  API  
    Request  +  Response  
     
    Explanafor  each  parameter  
    

    View Slide

19. Building  Documenta@sco8efein    
    

    View Slide

20. Create  an  API  Spec  
    @sco8efein    
    

    View Slide

21. RAMLSpec  
    Made  up  of  YAML,  
    JSON,  and  Markdown  
    @sco8efein    
    

    View Slide

22. JSONSchema  
    @sco8efein    
    

    View Slide

23. Swagger  2.0  
    @sco8efein    
    

    View Slide

24. API  Blueprint  
    

    View Slide

25. Genera

    View Slide

26. Genera@sco8efein    
    

    View Slide

27. ParGenerate  +  Update  Code-­‐Level  
    Parts  of  the  Spec  
     
    Leave  Blanks  for  DocumentaFields  
    @sco8efein    
    

    View Slide

28. Grape  to  Swagger      
    w/  grape-­‐swagger  
     
    Rails  Serializers  to  Swagger    
    w/Swaggard  
     
    @sco8efein    
    

    View Slide

29. Hand-­‐Built  Specs  
    Workflow:  Add  a  new  resource,  commit  a  new  
    spec  for  it  
     
    CLI  Tools:  
    •  Scaffolding  
    •  Concatena•  Valida@sco8efein    
    

    View Slide

30. documenta  
    Created  raml_specs/ki8en.raml  
    Created  markdown_documentaCreated  schemas/ki8en_request.json  
    Created  schemas/ki8en_response.json  
    Created  examples/ki8en.json  
    @sco8efein    
    

    View Slide

31. From  Specs  to  Docs  
    @sco8efein    
    

    View Slide

32. View Slide

33. @sco8efein    
    

    View Slide

34. @sco8efein    
    

    View Slide

35. View Slide

36. Spec  -­‐>  SDKs  
    h8ps://github.com/swagger-­‐api/swagger-­‐
    codegen  
    h8ps://apimah8ps://github.com/mulesof/raml-­‐client-­‐
    generator  
    h8p://restunited.com/  
    h8ps://github.com/interagent/heroics  
    @sco8efein    
    

    View Slide

37. Takeaways  
    •  Have  an  API  Spec  
    •  Build  tooling  around  your  documentagenerakeep  everything  up  to  date  
    •  For  your  CLI  tool  generacodegangsta/cli  
    •  Good  API  Tools  that  scale  allow  you  to-­‐  
    –  Update  API  endpoints  faster  
    –  Keep  everything  consistent  
    –  Decrease  maintenance  effort  
    @sco8efein    
    

    View Slide

38. QuesFollow  Me  on  Twi8er  @sco8efein  
    

    View Slide