building adaptable apis with narwhl (api days paris)
DESCRIPTION
An updated version of my NARWHL talk given at API Days Paris.TRANSCRIPT
Intel Confidential — Do Not Forward
Taming The RESTed NARWHLAn Approach to Building Adaptable APIs
2
3
Is this RESTful?
http://api.example.com/events/query.json?id=87465
Twitter: @rzazueta http://www.narwhl.com
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"
...
]
Twitter: @rzazueta http://www.narwhl.com
5
Google: “What is a REST API?”
Twitter: @rzazueta http://www.narwhl.com
6
Consistency Counts
Twitter: @rzazueta http://www.narwhl.com
7
8
Introducing the RESTed NARWHL
A design framework to build RESTful
APIs intended for consumption by
applications built by people
Twitter: @rzazueta http://www.narwhl.com
9
I Want To Hear From YOU!
The RESTed NARWHL
http://www.narwhl.com
Twitter: @rzazueta http://www.narwhl.com
10
1. It’s how I describe intuitive APIs
Noun
As
Resource
With
Hyper
Links Twitter: @rzazueta http://www.narwhl.com
11
2. Narwhals are an awesome mashup
+ =
Twitter: @rzazueta http://www.narwhl.com
12
3. Narwhals are real.
Twitter: @rzazueta http://www.narwhl.com
13
Obligatory RMM Slide
Source: http://martinfowler.com/articles/richardsonMaturityModel.html
Twitter: @rzazueta http://www.narwhl.com
14
Use Cases Uncover Resources
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.
Twitter: @rzazueta http://www.narwhl.com
15
Use Cases Uncover Resources
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.
Twitter: @rzazueta http://www.narwhl.com
16
Use Cases Uncover Resources
Customers
Products
Categories
Shopping Cart
Store Admin
Twitter: @rzazueta http://www.narwhl.com
17
Endpoint Design Matters
/{resource_name}/{resource_identifier}
Twitter: @rzazueta http://www.narwhl.com
18
Endpoint Design Matters
/products/73924
Twitter: @rzazueta http://www.narwhl.com
19
Endpoint Design Matters
/categories/39/products/73924
Twitter: @rzazueta http://www.narwhl.com
20
Endpoint Design Matters
Link: <http://api.example.com/products/73924>; rel="canonical"
Twitter: @rzazueta http://www.narwhl.com
21
Content Negotiation
WWBD?
Twitter: @rzazueta http://www.narwhl.com
22
Content Negotiation
application/x-shockwave-flash
Twitter: @rzazueta http://www.narwhl.com
Content Negotiation
Twitter: @rzazueta http://www.narwhl.com
Content Negotiation
Twitter: @rzazueta http://www.narwhl.com
25
Content Negotiation – Better Communication;
Saner Versioning
Start using specific MIME types in your responses –
even custom ones.
NOContent-Type: application/json
YESContent-Type: application/json;vnd.example.products+v1
26
Content Negotiation – Shared Profiles
Twitter: @rzazueta http://www.narwhl.com
27
Content Negotiation – Custom Profiles
Twitter: @rzazueta http://www.narwhl.com
28
Which Hypermedia Format?
Twitter: @rzazueta http://www.narwhl.com
29
Dynamic Client Generation Through Response Profiles
Twitter: @rzazueta http://www.narwhl.com
30
SDKs Suck Because:
• They’re one more thing to maintain
• They often assume functionality outside the API
• They get bloated
Twitter: @rzazueta http://www.narwhl.com
31
SDKs Are Necessary Because:
• No one wants to spend time figuring out your API.
Twitter: @rzazueta http://www.narwhl.com
32
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
Twitter: @rzazueta http://www.narwhl.com
33
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
Twitter: @rzazueta http://www.narwhl.com
34
Don’t Make Me Beg…
The RESTed NARWHL
http://www.narwhl.com
Twitter: @rzazueta http://www.narwhl.com
Intel Confidential — Do Not Forward
Thank You!Rob Zazueta
@rzazueta
http://www.NARWHL.com
35