5 Keys to API Design
Daniel Feist @dfeist
Principal Architect, MuleSoft

@MuleSoft
Me?
Me?
Me?
Me?
APIs:
The Cat's Meow
The New Enterprise

All contents Copyright © 2013, MuleSoft
Inc.

7
The New Enterprise

SaaS
Cloud platforms

Social

Mobility and Devices

Customers / Partners
/ Suppliers

Packaged apps

C...
The New Enterprise

1,000s
100s

SaaS

Cloud platforms

Social

1,000,000,000s

100,000s

Mobility and Devices

Customers ...
The New Enterprise

SaaS
Social

Cloud platforms

Open web APIs
Mobility and Devices

Customers / Partners / Suppliers

B2...
API Design
#1
The Contract is Critical
The API Contract Is Critical

•  tells consumer devs what they'll get

•  tells implementer devs what to deliver

•  enabl...
The Contract is Critical

ü  where consumers touch you
ü  your front door, your lobby, your façade
ü  how you want to b...
What kind of contract do we want?

1.  Describe APIs simply and clearly

2.  Design APIs easily and soundly
What kind of contract do we want?

Document your API?

or
Model your API?
#2
Design to Delight
The Key to API Success?

how?
• 
• 
• 
• 

design for them
iterate quickly
model cleanly and consistently
gather feedback
#3
Think APX not API
Design For Your Users

UI à UX
Valida
te

API à APX

Capture
Feedback
Think APX!
This is a long-lived interface,
ladies and gentlemen

Don't expose dirty laundry

!

users

products
orders

è...
#4
Use Patterns
Pattern Lifecycle

Define

Share

Reuse
Types of Patterns

•  Resource Types
•  Collection
•  Collection Member
•  Document

•  Traits
•  Secure
•  Paged
#5
Engage Developers
Engage Developers

•  Social Tools
•  Rate, discuss
•  Provide feedback

•  Interactive Console
•  Prototyping Tools
What Do People Do Today?
WADL
Reverb Swagger
Mashery IOdocs
Google Discovery Docs
Apiary Blueprint
Verdict:

manifest
structure

capture
patterns

humanly
writeable

let's try
harder…
Start From Scratch?
Really???
No Need to Start From Scratch!

• 
• 
• 
• 
• 
• 

well-known superset of JSON
optimized for human readability
great for h...
RAML

RESTful API Modeling Language
A new open spec
for RESTful APIs
that's as clean
and as structured
as REST itself
the ...
RAML: How Clean? How Structured?
RAML: Clean & Structured.
RAML: Reuse

resource type
schema

trait
Covers Full HTTP
optional version in baseUri
template URIs

query parameters

headers (on request and response)
response p...
Patterns: Resource Types
externalizable
inheritance
pull in traits

parametrize
Patterns: Method-level traits

mix-ins
Patterns: body schemas
XML schema
JSON schema
or just use good ol'
form data:

examples
Patterns: security schemes
username/password; cleartext or use digest
end user allows app to access their data
better to p...
What's next?

q growing library of API specs in RAML (e.g. on APIhub)
q converters (import WADL, Swagger etc.)
q client...
Interesting?
Thank you!
5 Keys to API Design - API Days Paris 2013
5 Keys to API Design - API Days Paris 2013
5 Keys to API Design - API Days Paris 2013
Upcoming SlideShare
Loading in...5
×

5 Keys to API Design - API Days Paris 2013

1,027

Published on

Published in: Technology
0 Comments
3 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
1,027
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
40
Comments
0
Likes
3
Embeds 0
No embeds

No notes for slide

5 Keys to API Design - API Days Paris 2013

  1. 1. 5 Keys to API Design Daniel Feist @dfeist Principal Architect, MuleSoft @MuleSoft
  2. 2. Me?
  3. 3. Me?
  4. 4. Me?
  5. 5. Me?
  6. 6. APIs: The Cat's Meow
  7. 7. The New Enterprise All contents Copyright © 2013, MuleSoft Inc. 7
  8. 8. The New Enterprise SaaS Cloud platforms Social Mobility and Devices Customers / Partners / Suppliers Packaged apps Custom apps Big Databases / Big Files
  9. 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. 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. 11. API Design
  12. 12. #1 The Contract is Critical
  13. 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. 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. 15. What kind of contract do we want? 1.  Describe APIs simply and clearly 2.  Design APIs easily and soundly
  16. 16. What kind of contract do we want? Document your API? or Model your API?
  17. 17. #2 Design to Delight
  18. 18. The Key to API Success? how? •  •  •  •  design for them iterate quickly model cleanly and consistently gather feedback
  19. 19. #3 Think APX not API
  20. 20. Design For Your Users UI à UX Valida te API à APX Capture Feedback
  21. 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. 22. #4 Use Patterns
  23. 23. Pattern Lifecycle Define Share Reuse
  24. 24. Types of Patterns •  Resource Types •  Collection •  Collection Member •  Document •  Traits •  Secure •  Paged
  25. 25. #5 Engage Developers
  26. 26. Engage Developers •  Social Tools •  Rate, discuss •  Provide feedback •  Interactive Console •  Prototyping Tools
  27. 27. What Do People Do Today?
  28. 28. WADL
  29. 29. Reverb Swagger
  30. 30. Mashery IOdocs
  31. 31. Google Discovery Docs
  32. 32. Apiary Blueprint
  33. 33. Verdict: manifest structure capture patterns humanly writeable let's try harder…
  34. 34. Start From Scratch? Really???
  35. 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. 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. 37. RAML: How Clean? How Structured?
  38. 38. RAML: Clean & Structured.
  39. 39. RAML: Reuse resource type schema trait
  40. 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. 41. Patterns: Resource Types externalizable inheritance pull in traits parametrize
  42. 42. Patterns: Method-level traits mix-ins
  43. 43. Patterns: body schemas XML schema JSON schema or just use good ol' form data: examples
  44. 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. 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. 46. Interesting?
  47. 47. Thank you!
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×