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

API Design with Apiary 2

Cb2527e0c321fc1eb6753c06f45da93c?s=47 Z
May 26, 2016

API Design with Apiary 2

Cb2527e0c321fc1eb6753c06f45da93c?s=128

Z

May 26, 2016
Tweet

Transcript

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

  2. API DESIGN PLATFORM

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

  4. API DESIGN

  5. 4 STAGES OF API DESIGN

  6. 4 STAGES OF API DESIGN 1 By-product

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

  8. 4 STAGES OF API DESIGN 1 2 3 By-product Generated

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

    Generated Docs Design-first Design Consistency
  10. IF API IS A PRODUCT TREAT IT AS A PRODUCT

  11. DESIGN-FIRST

  12. EMAIL STORY

  13. EMAIL STORY

  14. EMAIL STORY

  15. EMAIL STORY

  16. RE: RE: RE: RE: RE: RE: RE: RE: API WE

    WANT TO BUILD
  17. API DESCRIPTION

  18. API DESCRIPTION • API Blueprint • OpenAPI Specification (Swagger) •

    Others (RAML, WADL, WSDL, Email, Word document)
  19. API BLUEPRINT

  20. OPEN API SPEC

  21. API DESIGN WITH APIARY

  22. APIARY API Design API Prototyping API Documentation API Testing API

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

    API Debugger API Consistency
  24. API DESIGN

  25. API DESIGN API Description • Contract • Product Owner •

    Backed Developers • Customers • Tech Writers
  26. API PROTOTYPING

  27. API PROTOTYPING • Automatically generated • Driven by contract •

    First-moment of truth • Enables client development Mock Server
  28. API PROTOTYPING

  29. API DOCUMENTATION

  30. API DOCUMENTATION Documentation • Interactive documentation • Automatically generated •

    Driven by contract • Language examples • Console
  31. API DOCUMENTATION

  32. API TESTING

  33. API TESTING Tests in CI Local Tests • Verify implementation

    • Driven by contract
  34. API TESTING github.com/apiaryio/dredd

  35. API CALL DEBUGGER

  36. API CALL DEBUGGER Call Debugger • Introspect calls • Diff

    real vs. expected • Driven by contract
  37. API CALL DEBUGGER

  38. INTEGRATED

  39. CONTRACT-DRIVEN API Description Tests in CI Local Tests Call Debugger

    Documentation Mock Server
  40. API FLOW

  41. 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
  42. 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
  43. TRY IT NOW http://apiary.io Q&A @apiaryio

  44. None
  45. apiary.io/how-to-build-api

  46. None
  47. MIND SHIFT • Describe resource NOT representation • Define domain

    semantics • Reuse common semantics • Do NOT focus on technical details • URIs • representations • schema validations
  48. API ISN’T… • API is not pretty URLs • API

    is not HTTP Verbs • API is not CRUD • API is not JSON
  49. 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
  50. REFERENCE • http://apiary.io • http://apiblueprint.org • https://github.com/apiaryio/mson • http://www.ics.uci.edu/~fielding/pubs/dissertation/ rest_arch_style.htm