Successfully reported this slideshow.

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

0

Share

Loading in …3
×
1 of 25
1 of 25

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

0

Share

Download to read offline

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

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

More Related Content

Related Books

Free with a 30 day trial from Scribd

See all

Related Audiobooks

Free with a 30 day trial from Scribd

See all

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

  1. 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. © 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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

Editor's Notes

  • 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.
  • ×