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

API Design with Apiary 2

Z
May 26, 2016

API Design with Apiary 2

Z

May 26, 2016
Tweet

More Decks by Z

Other Decks in Programming

Transcript

  1. API DESIGN WITH APIARY
    Z (@zdne)
    apiary.io

    View full-size slide

  2. API DESIGN PLATFORM

    View full-size slide

  3. API projects managed
    Developers visit / month
    200,000+
    2M

    View full-size slide

  4. 4 STAGES OF API DESIGN

    View full-size slide

  5. 4 STAGES OF API DESIGN
    1
    By-product

    View full-size slide

  6. 4 STAGES OF API DESIGN
    1 2
    By-product Generated
    Docs

    View full-size slide

  7. 4 STAGES OF API DESIGN
    1 2 3
    By-product Generated
    Docs
    Design-first

    View full-size slide

  8. 4 STAGES OF API DESIGN
    1 2 3 4
    By-product Generated
    Docs
    Design-first Design
    Consistency

    View full-size slide

  9. IF API IS A PRODUCT
    TREAT IT AS A PRODUCT

    View full-size slide

  10. DESIGN-FIRST

    View full-size slide

  11. RE: RE: RE: RE: RE: RE: RE: RE:
    API WE WANT TO BUILD





























    View full-size slide

  12. API DESCRIPTION

    View full-size slide

  13. API DESCRIPTION
    • API Blueprint
    • OpenAPI Specification (Swagger)
    • Others (RAML, WADL, WSDL, Email, Word document)

    View full-size slide

  14. API BLUEPRINT

    View full-size slide

  15. OPEN API SPEC

    View full-size slide

  16. API DESIGN WITH APIARY

    View full-size slide

  17. APIARY
    API Design
    API Prototyping
    API Documentation
    API Testing
    API Debugger
    API Consistency

    View full-size slide

  18. APIARY
    INTEGRATED
    API Design
    API Prototyping
    API Documentation
    API Testing
    API Debugger
    API Consistency

    View full-size slide

  19. API DESIGN
    API Description • Contract
    • Product Owner
    • Backed Developers
    • Customers
    • Tech Writers

    View full-size slide

  20. API PROTOTYPING

    View full-size slide

  21. API PROTOTYPING
    • Automatically generated
    • Driven by contract
    • First-moment of truth
    • Enables client development
    Mock Server

    View full-size slide

  22. API PROTOTYPING

    View full-size slide

  23. API DOCUMENTATION

    View full-size slide

  24. API DOCUMENTATION
    Documentation • Interactive documentation
    • Automatically generated
    • Driven by contract
    • Language examples
    • Console

    View full-size slide

  25. API DOCUMENTATION

    View full-size slide

  26. API TESTING
    Tests in CI
    Local Tests
    • Verify implementation
    • Driven by contract

    View full-size slide

  27. API TESTING
    github.com/apiaryio/dredd

    View full-size slide

  28. API CALL DEBUGGER

    View full-size slide

  29. API CALL DEBUGGER
    Call Debugger • Introspect calls
    • Diff real vs. expected
    • Driven by contract

    View full-size slide

  30. API CALL DEBUGGER

    View full-size slide

  31. CONTRACT-DRIVEN
    API Description
    Tests in CI
    Local Tests
    Call Debugger
    Documentation
    Mock Server

    View full-size slide

  32. 1
    PREPA
    RATIO
    N
    API FLOW
    D
    ESIG
    N
    D
    EVELO
    PM
    EN
    T
    D
    ELIVERY
    C
    O
    N
    SU
    M
    PTIO
    N
    A
    N
    A
    LYSIS
    2 3 4 5 6

    View full-size slide

  33. 1
    PREPA
    RATIO
    N
    API FLOW
    D
    ESIG
    N
    &
    PRO
    TO
    TYPE
    D
    EVELO
    PM
    EN
    T
    D
    ELIVERY
    C
    O
    N
    SU
    M
    PTIO
    N
    A
    N
    A
    LYSIS
    2 3 4 5 6

    View full-size slide

  34. TRY IT NOW
    http://apiary.io
    Q&A
    @apiaryio

    View full-size slide

  35. apiary.io/how-to-build-api

    View full-size slide

  36. MIND SHIFT
    • Describe resource NOT representation
    • Define domain semantics
    • Reuse common semantics
    • Do NOT focus on technical details
    • URIs
    • representations
    • schema validations

    View full-size slide

  37. API ISN’T…
    • API is not pretty URLs
    • API is not HTTP Verbs
    • API is not CRUD
    • API is not JSON

    View full-size slide

  38. REST ARCHITECTURAL STYLE
    • Client–server
    • Stateless
    • Cacheable
    • Layered system
    • Code on Demand (optional)
    • Uniform Interface
    • Identification of resources
    • Manipulation through representations
    • Self-descriptive messages
    • Hypermedia as the engine of the application state

    View full-size slide

  39. REFERENCE
    • http://apiary.io
    • http://apiblueprint.org
    • https://github.com/apiaryio/mson
    • http://www.ics.uci.edu/~fielding/pubs/dissertation/
    rest_arch_style.htm

    View full-size slide