Taming the RESTed NARWHL: Striking the Balance Between Usability and Zealotry in REST.

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!

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.