#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://stackoverflow.com/questions/2217758/what-is-a-rest-api 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
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