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
45. apiary.io/how-to-build-api
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