-
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
Thank you for listening to me yammer for the next 30 minutes.
I love the API community. There are incredibly smart and passionate people who are eager to connect us to the future. I have a great deal of respect for all of them and their ideas and I love jumping into the fray on the API Craft group, at conferences like RESTfest and, of course, right here at Gluecon.
I can not stand peoplewho identify problems without suggesting solutions. I tend to believe you become part of the problem at that point.
Don’t let your API’s design surprise your developer customers; surprise them, instead, with the cool things you can do with it.
This is perhaps the most important point. APIs can not live in the abstract and expect to survive – they need to get out there and be used. NARWHL is intended for teams who need to get past the debate and build an API today.
No talk about RESTful APIs can be legally delivered without mentioning both Roy Fielding’s 2000 thesis and the Richardson Maturity Model. IF you leave it out, expect to get a ticket in the mail.
NARWHL starts where the RMM ends. It is by default intended to be RMM Level 3 compliant, but to add some additional structure based on best practices that are already in the wild and that are recommended.
I’m not talking about anything revolutionary here – this should look familiar to you. And that’s the point.