#GlueCon 2014 Keynote: Taming the RESTed NARWHL: Striking the Balance Between Usability and Zealotry in REST – Rob Zazueta, Mashery (an Intel Company)
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