API Design with Apiary 2

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