In the presentation from Gluecon 2014, Rob Zazueta - Director, Platform Strategy at Mashery, an Intel Company - introduces his API design framework intended to help developers implementing an API cut through the RESTful debates to get to what worksbest. For more information, please visit http://www.narwhl.com

1. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
Taming The RESTed NARWHL
Striking the Balance Between
Usability and Zealotry in REST

2. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
2

3. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
3
Is this RESTful?
http://api.example.com/events/query.json?id=87465

4. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
4
What About This?
Find “Rob Zazueta” in the employee Database.
GET /countries
[
"/countries/usa/states",
"/countries/can/provinces",
...
]
GET /countries/usa/states
[
"/countries/usa/states/al",
"/countries/usa/states/ak",
...
]
GET /countries/usa/states/ca
[
"/countries/usa/states/ca/divisions",
"/countries/usa/states/ca/employees",
...
]
GET /countries/usa/states/ca/employees
[
"/countries/usa/states/ca/employees/alan_akbar",
"/countries/usa/states/ca/employees/bill_allen"
...
]

5. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
5
“What is a REST API?”

6. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
A design framework to build RESTful
APIs intended for consumption by
applications built by people
6
Introducing the RESTed NARWHL

7. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
The RESTed NARWHL
http://www.narwhl.com
7
PLEASE PROVIDE YOUR FEEDBACK!

8. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
8

9. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
Noun
As
Resource
With
Hyper
Links
9
1. It’s how I describe intuitive APIs

10. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
10
2. Narwhals are an awesome mashup
+ =

11. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
11
3. Narwhals are real.

12. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
12
Obligatory RMM Slide
Source: http://martinfowler.com/articles/richardsonMaturityModel.html

13. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
• A customer wants to browse for products by
category.
• A customer wants to add a product to their
shopping cart.
• A store admin wants to list all customers who
bought a given product.
13
Use Cases Uncover Resources

14. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
• A customer wants to browse for products by
category.
• A customer wants to add a product to their
shopping cart.
• A store admin wants to list all customers who
bought a given product.
14
Use Cases Uncover Resources

15. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
• Customers
• Products
• Categories
• Shopping Cart
• Store Admin
15
Use Cases Uncover Resources

16. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
16
Endpoint Design Matters
/{resource_name}/{resource_identifier}

17. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
17
Endpoint Design Matters
/products/73924

18. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
18
Endpoint Design Matters
/categories/39/products/73924

19. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
19
Endpoint Design Matters
Link: <http://api.example.com/v1/products/73924>; rel="canonical"

20. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
Start using specific MIME types in your
responses – even custom ones.
NO - Content-Type: text/json
YES – Content-Type:
application/vnd.example.products.json+v1
20
Saner Versioning Through Content Negotiation

21. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
SDKs Suck Because:
• They’re one more thing to maintain
• They often assume functionality outside the API
• They get bloated
21Dynamic Client Generation Through Response Profiles

22. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
Dynamic Code Libraries Rock Because:
• They reflect only what’s defined in the API
• They grow and change as the API iterates
• They feel more native to the developer
22Dynamic Client Generation Through Response Profiles

23. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
23
NARWHL Maturity Model*
Level 0: Nouns as Resources With Hyperlinks
Level 1: NARWHL JSON Responses
Level 2: Content Negotiation
Level 3: Response Profiles & Definitions
Awesomeness of NARWHL
*With apologies and thanks to Martin Fowler and Leonard Richardson

24. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
The RESTed NARWHL
http://www.narwhl.com
24
SERIOUSLY. DON’T MAKE ME BEG.

25. © 2 0 1 4 M a s h e r y , I n c . — P R O P R I E T A R Y A N D C O N F I D E N T I A L
25