Chapter 05: Standards vs. Conventions

The REST constraints defined by Fielding and Richardson’s model, as described in the previous chapters, represent more of an abstract outline of ideal communication on the web. As you’ll agree, this knowledge alone doesn’t tell us much about how to design a usable API that developers will actually love. Our journey through the world of REST APIs must therefore inevitably move on to the standards and conventions that have emerged over the past decades. We’re going to need both.

Technical standards define specific rules that developers should follow when building web services. Yet their practical application often leads to different results. How is that possible? For instance, the HTTP standard precisely describes the structure of a URL but says nothing about how URLs should be used for pagination in a web service. And this is exactly where conventions come in — practices that the developer community has adopted and informally standardized over the past decade.