RESTful Node.js: A Structured Approach
  • Book Cover
  • About the Author
  • Links and Resources
  • Part I: The Why
    • Foreword
    • Preface
    • Chapter 1: Introduction
      • The Rise of REST and Distributed Systems
      • Problem #1: Structureless Design, Structureless REST
      • The Emergence of JavaScript and Node.js
      • Problem #2: Structureless JavaScript, Structureless Node.js
      • Behold, the Solution: A Structured Approach
      • Summary
  • Part 2: The Theory
    • Chapter 2: REST Origins
      • A Brief History of the Web and the Birth of REST
      • REST vs. HTTP
      • REST - The Abstract Web Architecture
      • HTTP - A Peak at REST's Concrete Implementation
      • What does it mean for an API to be RESTful?
      • Measuring "RESTfulness" with Richardson Maturity Model
      • Pragmatic REST vs Dogmatic REST
      • Summary
    • Chapter 3: RESTful API Design Guidelines and "Best Practices"
      • Theories vs. Principles vs. Guidelines
      • URI Design
      • Method Verbs
      • Status Codes
      • Representational Design
      • Metadata Design
      • Versioning Strategies
      • Security Considerations
      • Documentation
      • Case Study: GitHub
      • Summary
    • Chapter 4: Structured JavaScript Architecture
      • The Monstrous Monolith and Its Downfall
      • Layered/N-Tier Architecture: The Unpopular Proven Way
      • Microservices and Distributed Computing: A Popular Misdirection
      • Summary
    • Chapter 5: The 8 Step Recipe
      • Route Name (URI)
      • Input Request
      • Middleware
      • Validation
      • Domain
      • Events
      • Output Response
      • Test, Refactor, Document
      • Summary
  • Part 3: The Code
    • Chapter 6: Introduction to the Bookstore API
      • The Bookstore API Endpoint Specifications
      • API Design and Code Structure
      • Project Setup
      • Summary
    • Chapter 7: Retrieving Books from our API
      • Retrieving All Books - Planning
      • Retrieving All Books - Implementation
      • Retrieving A Book By ID - Planning
      • Retrieving A Book By ID - Implementation
      • Summary
    • Chapter 8: Adding Authentication to our API
      • Registering the User - Planning
      • Registering the User - Implementation
      • Logging the User In - Planning
      • Logging the User In - Implementation
      • Getting Authenticated User - Planning
      • Getting Authenticated User - Implementation
      • Summary
    • Chapter 9: Adding the Create, Update, and Delete Operations to our API
      • Creating A Book Listing - Planning
      • Creating A Book Listing - Implementation
      • Updating A Book Listing By ID - Planning
      • Updating A Book Listing By ID - Implementation
      • Deleting A Book Listing By ID - Planning
      • Deleting A Book Listing By ID - Implementation
      • Summary
    • Chapter 10: Testing our API
      • Testing the Request
      • Testing the Middleware
      • Testing the Validation
      • Testing the Domain
      • Testing the Event
      • Testing the Response
      • Testing the Controller
      • Integration Test
      • Summary
  • Conclusion
    • Final Words
  • Bonus!
    • Refactoring to HATEOAS
  • Appendix
    • Sources & References
Powered by GitBook
On this page
Edit on GitHub
  1. Part 2: The Theory
  2. Chapter 2: REST Origins

Pragmatic REST vs Dogmatic REST

PreviousMeasuring "RESTfulness" with Richardson Maturity ModelNextSummary

Last updated 3 years ago

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 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.

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

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 .

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 .

your needs
final bonus chapter
Zalando's public API guidelines
https://opensource.zalando.com/restful-api-guidelines/#hypermedia