$30 off During Our Annual Pro Sale. View Details »

API Design Lifecycle @ Rubyslava Conf'15

API Design Lifecycle @ Rubyslava Conf'15

As APIs are often sitting on boundaries between groups of developers with very different expectations and use cases, problems resulting from one-sided waterfall development are even worse than usual. First part of my talk will show you how to avoid waterfalls by employing iterations, prototyping, communication with client developers and testing. The second part of the presentation will be focused on how API Blueprint and its ecosystem fit into this concept and how they help to deliver APIs the right way. I'll present new API Blueprint and Apiary features and I'll also give some sneak peeks on still to be announced features (shshshsh!), which can help you to get the most from the API Blueprint and Apiary.

Honza Javorek

June 19, 2015
Tweet

More Decks by Honza Javorek

Other Decks in Technology

Transcript

  1. API Design Life Cycle
    HONZA JAVOREK

    View Slide

  2. Czech Python Community Mascot
    API design lover
    Honza Javorek
    honzajavorek.cz @honzajavorek
    sort of cartoonist
    beverage-agnostic caffeine consumer

    View Slide

  3. 1 what's wrong on classic API design
    2 how to do it better
    3 how can Apiary help

    View Slide

  4. How do people design and
    develop APIs?

    View Slide

  5. View Slide

  6. View Slide

  7. View Slide

  8. 70s
    40 years ago

    View Slide

  9. 70s
    40 years ago
    Karel Gott
    Waldemar
    Matuška
    Blue Effect
    Helena
    Vondráčková
    Miroslav
    Žbirka
    waterfall model
    coined
    AC/DC
    Led Zeppelin

    View Slide

  10. API is an interface

    View Slide

  11. API is an interface
    to data

    View Slide

  12. API is an interface
    to data
    for client developers

    View Slide

  13. For who?

    View Slide

  14. Mobile App Hippie
    Frontend Samurai
    Klientína Vývojárková
    chocolate core commiter
    guerilla gardening evangelist
    example.com/klientina

    View Slide

  15. Human
    helpful error messages
    consistency
    error prevention
    usability
    naming
    ProTip™: read Jakob Nielsen
    use case oriented
    help & documentation

    View Slide

  16. Different concerns
    maintenance
    Rails
    Django
    SQL
    caching
    JBoss
    storage
    uptime
    versioning
    ORM
    security

    View Slide

  17. Different concerns
    maintenance
    Rails
    SQL
    JBoss
    uptime
    security
    Objective-C
    latency
    JavaScript
    how to…?
    jQuery
    Angular
    examples
    learning curve
    debugging

    View Slide

  18. Different culture
    öl_pris cenaPiva
    BeerPrice
    precio-de-la-cerveza
    !r #ைல
    SörÁra

    View Slide

  19. EMPATHY IS HARD!

    View Slide

  20. prototypes
    iterations
    communication
    co-operation
    documentation
    design first
    use cases

    View Slide

  21. View Slide

  22. But how?

    View Slide

  23. API Blueprint

    View Slide

  24. View Slide

  25. Markdown file

    View Slide

  26. View Slide

  27. View Slide

  28. Design
    Prototype
    Implementation
    Delivery
    Feedback

    View Slide

  29. Design
    Prototype
    Implementation
    Delivery
    Feedback

    View Slide

  30. Documentation
    Tests
    Mock Server
    Debugging Proxy Server
    GitHub
    JSON Schema
    Sublime Text Plugin
    Style Checking
    Atom Plugin
    Node.js binding
    Ruby binding
    Validation
    Vim Plugin
    SoapUI Plugin
    Hypermedia
    Open Source
    apiblueprint.org
    language-agnostic

    View Slide

  31. Apiary
    apiary.io

    View Slide

  32. Documentation

    View Slide

  33. Documentation: MSON
    sneak peek
    github.com/apiaryio/mson

    View Slide

  34. Mock Server

    View Slide

  35. Debugging Proxy Server

    View Slide

  36. Tests and Cont. Integration
    sneak peek

    View Slide

  37. View Slide

  38. Full GitHub workflow
    sneak peek

    View Slide

  39. Style checking
    "enterprise" feature

    View Slide

  40. Want to try?
    [email protected]
    @apiaryio

    View Slide

  41. Authentication Syntax?
    PR #201
    github.com/apiaryio/api-blueprint/pull/201
    Give us feedback!

    View Slide

  42. Image Credits
    Leonardo da Vinci - Le proporzioni del corpo umano secondo Vitruvio, 1490
    Honza Javorek - arbitrary cartoons, 2O14 and 2015

    View Slide

  43. apiblueprint.org
    github.com/apiaryio
    apiary.io

    View Slide