5 Keys to API Design - API Days Paris 2013

  • 665 views
Uploaded on

 

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads

Views

Total Views
665
On Slideshare
0
From Embeds
0
Number of Embeds
2

Actions

Shares
Downloads
31
Comments
0
Likes
2

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 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: raml.org
  • 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!