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 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