Pragmatic REST vs Dogmatic REST
Last updated
Last updated
Pragmatism is a philosophical tradition that considers words and thought as tools and instruments for prediction, problem solving, and action, and rejects the idea that the function of thought is to describe, represent, or mirror reality. Pragmatists contend that most philosophical topics—such as the nature of knowledge, language, concepts, meaning, belief, and science—are all best viewed in terms of their practical uses and successes.
-Wikipedia
Dogmatism in the broad sense is any belief held unquestioningly and with undefended certainty. It may be in the form of an official system of principles or doctrines of a religion, such as Roman Catholicism or Protestantism, as well as the positions of a philosopher or of a philosophical school such as Stoicism.
-Wikipedia
Building RESTful APIs is challenging by nature, we've discovered in the prior section what it really means for an API to be truly "RESTful". This is why it is important to consider the realities of pragmatism over dogmatism when it comes to building and designing APIs, because there is no definite right answer when it comes to that.
An example of pragmatism is Zalando's public API guidelines where every API endpoint created must have a "REST maturity level 2", but a "REST maturity level 3" is optional. Notice the fluidity of such guidelines is what makes this so practical in real world uses.
In fact, there are plenty of companies that do not have a truly RESTful API. Examples include APIs from Amazon, Ebay, Instagram, and even Google.
Perhaps REST may just not be for you, there plenty of other architectural styles out there. There's GraphQL, gRPC, SOAP, and many more. My suggestion is pick one that suits your needs.
I'm still not on board with doing this (adding hypermedia links) in each and every project, but there are projects, especially ones that may be generatively created, that can benefit from using hypermedia. I think it's one of those things that the complexity it adds isn't always worth the cost of actually developing it. It depends, again, on your users and the requirements. Ultimately I think pragmatism needs to win here and that most projects that I've dealt with don't need hypermedia, but every once in a while it comes and it's super useful, so understanding it as something you can optionally include in your APIs is important. I just don't want to get stuck in that if it doesn't include hypermedia or links to other parts that are self-describing, that you're purposely not RESTful.
-Shawn Wildermuth, Microsoft MVP
With all that being said, we will not be designing and building a fully hypermedia-friendly API in the main parts of the book. However, we will be refactoring our final project and make it hypermedia-friendly with links in a final bonus chapter.
