James Higginbotham

API Architect

#GlueCon 2014 Keynote: Taming the RESTed NARWHL: Striking the Balance Between Usability and Zealotry in REST – Rob Zazueta, Mashery (an Intel Company)

1 minute read

Keynote: Taming the RESTed NARWHL: Striking the Balance Between Usability and Zealotry in REST – Rob Zazueta, Mashery (an Intel Company)

  • For those charged with writing books about API design, debates might be useful
  • But for those that just need to write APIs, it causes confusion
  • One end of the spectrum: REST APIs that have IDs as URL params, preventing caching but still REST
  • The other end of the spectrum: Too many levels of traversal by being too strict with resources but still REST
  • Stackoverflow answer for what is REST demonstrates that we aren’t explaining or helping REST but rather making it confusing or wrong
  • http://www.narwhl.com/
  • Don’t have your customers be confused when they want to consume your API – instead, surprise them in a good way with great functionality
  • Noun As Resource With Hyper Links (NARWHL)
  • We want to get to level 3 on the Richardson Maturity Model
  • To get there, we have to uncover resources by doing analysis and modeling
  • We also need to use HTTP how it was designed, using URIs that can be cached and MIME types for content and versioning
  • SOAP sucks, except for the WSDL to allow clients to autogenerate dynamic client libraries that hide the network library calls
  • Definition languages: iodocs, RAML, and Swagger are the big three
  • Dynamic code libraries feel more native to the developer
  • If we use a definition language, we can allow mere mortals to do what they can do with IFTTT today, but even better
  • The NARWHL framework is meant to help get people started on the right path to building RESTful APIs
  • An SDK that is focused on one API is a single use tool that has to be maintained
  • A dynamic code library could be pointed to a Definition Language and auto-generate a native-feeling wrapper around the API without building SDKs for every API for every language
  • Q: How nested should your resources be? A: Anything over 3 is sufficient, deeper is bad design and will be confusing. This requires normalization (and denormalization) of resources

You May Also Enjoy