5 Keys to API Design - API Days Paris 2013
4 likes•1,465 views
This document discusses 5 keys to API design: 1) The API contract is critical as it tells developers what to expect and deliver, enables parallel development, and ensures requirements are met. 2) Design to delight users by gathering feedback and iterating quickly. 3) Think of APIs as APX (API Experience) and craft them for user enjoyment. 4) Leverage patterns for resource types, collections, traits and more. 5) Engage developers through social tools, interactive consoles and prototyping tools to get their feedback. The document also promotes the RAML specification for modeling RESTful APIs in a clean, structured way.
5 Keys to API Design - API Days Paris 2013
- 1. 5 Keys to API Design Daniel Feist @dfeist Principal Architect, MuleSoft @MuleSoft
- 2. Me?
- 3. Me?
- 4. Me?
- 5. Me?
- 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?
- 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
- 24. Types of Patterns • Resource Types • Collection • Collection Member • Document • Traits • Secure • Paged
- 26. Engage Developers • Social Tools • Rate, discuss • Provide feedback • Interactive Console • Prototyping Tools
- 28. What Do People Do Today?
- 29. WADL
- 30. Reverb Swagger
- 31. Mashery IOdocs
- 33. Apiary Blueprint
- 36. 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
- 37. 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
- 38. RAML: How Clean? How Structured?
- 39. RAML: Clean & Structured.
- 41. 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
- 42. Patterns: Resource Types externalizable inheritance pull in traits parametrize
- 44. Patterns: body schemas XML schema JSON schema or just use good ol' form data: examples
- 45. 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
- 47. 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)
- 49. Interesting?
- 50. Thank you!