taming the rested narwhl: striking the balance between usability and zealotry in rest
DESCRIPTION
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.comTRANSCRIPT
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY 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 TA RY 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 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
2
We Have a Problem
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
3Is this RESTful?
http://api.example.com/events/query.json?id=87465
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
4What 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" ...]
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
5“What is a REST API?”
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
6
A design framework to build RESTful APIs intended for consumption by
applications built by people
Introducing the RESTed NARWHL
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
7
The RESTed NARWHLhttp://
www.narwhl.com
PLEASE PROVIDE YOUR FEEDBACK!
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
8
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
9
NounAs ResourceWithHyperLinks
1. It’s how I describe intuitive APIs
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
102. Narwhals are an awesome mashup
+ =
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
113. Narwhals are real.
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
12Obligatory RMM Slide
Source: http://martinfowler.com/articles/richardsonMaturityModel.html
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
13
• 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.
Use Cases Uncover Resources
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
14
• 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.
Use Cases Uncover Resources
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
15
• Customers• Products• Categories• Shopping Cart• Store Admin
Use Cases Uncover Resources
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
16Endpoint Design Matters
/{resource_name}/{resource_identifier}
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
17Endpoint Design Matters
/products/73924
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
18Endpoint Design Matters
/categories/39/products/73924
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
19Endpoint Design Matters
Link: <http://api.example.com/v1/products/73924>; rel="canonical"
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
20
Start using specific MIME types in your responses – even custom ones.
NO - Content-Type: text/jsonYES – Content-Type:
application/vnd.example.products.json+v1
Saner Versioning Through Content Negotiation
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
21
SDKs Suck Because:• They’re one more thing to maintain• They often assume functionality outside the
API• They get bloated
Dynamic Client Generation Through Response Profiles
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
22
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
Dynamic Client Generation Through Response Profiles
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
23NARWHL 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
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
24
The RESTed NARWHLhttp://
www.narwhl.com
SERIOUSLY. DON’T MAKE ME BEG.
© 2 0 1 4 M a s h e r y , I n c . — P R O P R I E TA RY A N D C O N F I D E N T I A L
25