Your SlideShare is downloading. ×
5 Keys to API Design - API Days Paris 2013
Upcoming SlideShare
Loading in...5

Thanks for flagging this SlideShare!

Oops! An error has occurred.

Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

5 Keys to API Design - API Days Paris 2013


Published on

Published in: Technology
  • Be the first to comment

No Downloads
Total Views
On Slideshare
From Embeds
Number of Embeds
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

No notes for slide


  • 1. 5 Keys to API Design Daniel Feist @dfeist Principal Architect, MuleSoft @MuleSoft
  • 2. Me?
  • 3. Me?
  • 4. Me?
  • 5. Me?
  • 6. APIs: The Cat's Meow
  • 7. The New Enterprise All contents Copyright © 2013, MuleSoft Inc. 7
  • 8. The New Enterprise SaaS Cloud platforms Social Mobility and Devices Customers / Partners / Suppliers Packaged apps Custom apps Big Databases / Big Files
  • 9. The New Enterprise 1,000s 100s SaaS Cloud platforms Social 1,000,000,000s 100,000s Mobility and Devices Customers / Partners / Suppliers Packaged apps 1,000,000s Custom apps Big Databases / Big Files
  • 10. The New Enterprise SaaS Social Cloud platforms Open web APIs Mobility and Devices Customers / Partners / Suppliers B2B APIs Product APIs Internal APIs Packaged apps Custom apps The New Enterprise Databases
  • 11. API Design
  • 12. #1 The Contract is Critical
  • 13. The API Contract Is Critical •  tells consumer devs what they'll get •  tells implementer devs what to deliver •  enables parallel development •  ensures they'll meet in the end
  • 14. The Contract is Critical ü  where consumers touch you ü  your front door, your lobby, your façade ü  how you want to be seen; your brand ü  versioned more carefully than code ü  better interfaces è better code ü  an organizing principle; alignment forcing function ü  the ultimate testing surface
  • 15. What kind of contract do we want? 1.  Describe APIs simply and clearly 2.  Design APIs easily and soundly
  • 16. What kind of contract do we want? Document your API? or Model your API?
  • 17. #2 Design to Delight
  • 18. The Key to API Success? how? •  •  •  •  design for them iterate quickly model cleanly and consistently gather feedback
  • 19. #3 Think APX not API
  • 20. Design For Your Users UI à UX Valida te API à APX Capture Feedback
  • 21. Think APX! This is a long-lived interface, ladies and gentlemen Don't expose dirty laundry ! users products orders è invoices Craft it for your users: what will they love?
  • 22. #4 Use Patterns
  • 23. Pattern Lifecycle Define Share Reuse
  • 24. Types of Patterns •  Resource Types •  Collection •  Collection Member •  Document •  Traits •  Secure •  Paged
  • 25. #5 Engage Developers
  • 26. Engage Developers •  Social Tools •  Rate, discuss •  Provide feedback •  Interactive Console •  Prototyping Tools
  • 27. What Do People Do Today?
  • 28. WADL
  • 29. Reverb Swagger
  • 30. Mashery IOdocs
  • 31. Google Discovery Docs
  • 32. Apiary Blueprint
  • 33. Verdict: manifest structure capture patterns humanly writeable let's try harder…
  • 34. Start From Scratch? Really???
  • 35. No Need to Start From Scratch! •  •  •  •  •  •  well-known superset of JSON optimized for human readability great for hierarchies cruft-free broad tooling base extensible-ish
  • 36. RAML RESTful API Modeling Language A new open spec for RESTful APIs that's as clean and as structured as REST itself the RAML Workgroup:
  • 37. RAML: How Clean? How Structured?
  • 38. RAML: Clean & Structured.
  • 39. RAML: Reuse resource type schema trait
  • 40. Covers Full HTTP optional version in baseUri template URIs query parameters headers (on request and response) response per status code example (and schema) per media type
  • 41. Patterns: Resource Types externalizable inheritance pull in traits parametrize
  • 42. Patterns: Method-level traits mix-ins
  • 43. Patterns: body schemas XML schema JSON schema or just use good ol' form data: examples
  • 44. Patterns: security schemes username/password; cleartext or use digest end user allows app to access their data better to put token in header, not query the OAuth multi-step dance
  • 45. What's next? q growing library of API specs in RAML (e.g. on APIhub) q converters (import WADL, Swagger etc.) q client generators q server frameworks (e.g. MuleSoft APIkit; node.js) q JAX-RS Support q testing frameworks q mocking services (e.g. on APIhub) q <insert your ideas here> q evolve RAML spec (RAML workgroup)
  • 46. Interesting?
  • 47. Thank you!