REST Inspired Pragmatic Web-API Design

REST as defined by Roy Fielding exerts a wide influence yet is seldom adopted in toto. In Best Practices for a Pragmatic RESTful API Vinay Sahni summarizes factors that make an API flexible, easy to use, and easy to adopt. His post differs from Fielding's relatively abstract, theoretical definition of constraints and includes factors like security, documentation, versioning, and JSON style. While he includes some discussion about linking (pagination) he explicitly cites HATEOAS as not quite ready for prime time, a concern that has relatively broad consensus among API developers currently.

HATEOAS is still a topic of active interest of course. JSON API is a JSON-based read/write hypermedia-type designed to support a smart client who wishes build a data-store of information. Like the "Best Practices" post above, it is obviously REST inspired, but is tempered by concerns introduced by specific web application API design (the API is extracted from the JSON transport defined by Ember's REST adapter.)

Securing Web APIs is another practical topic not addressed by REST directory. James Ward presents a well articulated explanation of how to secure single page apps and REST services. In many cases, security is the determining factor on the viability of an API. Security is a practical constraint that influences the adoption of an API to a much greater extent than other specified constraints that comprise REST.

The definition of REST in its theoretical purity is immensely valuable. But the long term vision driving REST constraints introduces characteristics that are not flexible, easy to use, or easy to adopt. The history of the web shows that real-world practicality wins over theoretical purity in the web world. REST ought to continue be recognized in its function as a standard-bearer but most projects will benefit with clear articulation of how to apply its principles effectively given current development expectations.

comments powered by Disqus