A Shift of Mind

HTTP is legacy. Let's focus on architecture instead. API Craft 2014

Transcript

1. A SHIFT OF MIND Z – @zdne z@apiary.io
2. API BLUEPRINT apiblueprint.org
3. • Web API description language • Pure Markdown • Designed for humans • Understandable by machines • Open & Free API BLUEPRINT
4. API BLUEPRINT • Stop reinventing the wheel • Common tooling • Lingua Franca • API design tool
5. Launch API Craft 2013
6. over 80 000 APIs
7. Dozens of open source tools
8. DESIGN DECISIONS
9. HTTP-based
10. Architectural style-agnostic
11. Hypermedia is different
12. HTTP is legacy
13. Can’t see the architecture for the URLs
14. Time to move on
15. Design from abstract to concrete
16. Media-type and protocol are implementation details
17. Think ARCHITECTURE
18. Sharpen the TOOLS
19. RESOURCE BLUEPRINT
20. COMMUNITY
21. • Resource-oriented • Protocol-independent • Modeling Resources – attributes & affordances • API state machine RESOURCE BLUEPRINT
22. TOASTER AUTOMATON
23. TOASTER AUTOMATON Waiting Holding Bread Cooking Finite State Machine Insert Eject Cook Eject Set Cook Time Set Cook Time Set Cook Time
24. RESOURCE BLUEPRINT # Toaster Automaton API ! ## Resource Toaster ### Attributes - cook_time - toast
25. RESOURCE BLUEPRINT # Toaster Automaton API ! ## Resource Toaster ### Attributes - cook_time (number) - Cook time in seconds - toast - Toast inserted in the toaster, if any
26. RESOURCE BLUEPRINT # Toaster Automaton API ! ## Resource Toaster ### Attributes - cook_time (number) - Cook time in seconds - toast - Toast inserted in the toaster, if any ! ### Affordances - insert - eject - cook - set_cook_time
27. RESOURCE BLUEPRINT ### States - waiting - Affordances - insert -> holding_bread - set_cook_time -> waiting ! - holding_bread - Affordances - eject -> waiting - cook -> cooking - set_cook_time -> holding_bread ! - cooking - Affordances - eject -> waiting - set_cook_time -> cooking
28. PROFILE
29. Unparalleled TOOLS
30. Let’s work TOGETHER
31. API BLUEPRINT apiblueprint.org
32. • Resource Blueprint – https://github.com/apiaryio/api-blueprint/tree/ resource-blueprint • API Blueprint – http://apiblueprint.org • Apiary – http://apiary.io • API Craft – http://apicraft.org • Issue #13 – https://github.com/apiaryio/api-blueprint/issues/13 REFERENCE
33. TOASTER EVOLUTION Cooking Set Cook Time • Server stops offering set cook time in the cooking state • Client not following available affordances from server will break • Client following available affordances from server will stop showing the set cook time UI controls
34. TOASTER EVOLUTION Waiting Cooking Insert = Cook Eject Set Cook Time Set Cook Time • Toaster now immediately cooks after bread is inserted • Client not following available affordances from server will break • Client following available affordances from server will still be able to make a crispy toast
35. TOOLS PROLIFERATION • generate Blueprint from: JSON, YAML, cURL trace, RSpec ! • generate from Blueprint into: API reference, Postman collection, acceptance tests, client code, API mock, SDKs