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.

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

28. What Do People Do Today?

29. WADL

30. Reverb Swagger

31. Mashery IOdocs

32. Google Discovery Docs

33. Apiary Blueprint

34. Verdict:
manifest
structure
capture
patterns
humanly
writeable
let's try
harder…

35. Start From Scratch?
Really???

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.

40. RAML: Reuse
resource type
schema
trait

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

43. Patterns: Method-level traits
mix-ins

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!