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 3: RESTful API Design Guidelines and "Best Practices"

Theories vs. Principles vs. Guidelines

PreviousChapter 3: RESTful API Design Guidelines and "Best Practices"NextURI Design

Last updated 3 years ago

Before moving on to the best practices and guidelines, I want to emphasize a bit on the word "guideline".

In my final year of university, I took a class called taught by at the University of Toronto.

To be really honest, I didn't really pay much attention in that class, I only took this course in order to fulfill one of my upper-year computer science requirements. There was one lecture where I actually did take notes, and that lecture was about understanding the differences between theories, principles, and guidelines. Although that class that I took many years ago was on usability and interaction design, I will never forget what the differences between the three are.

Here are the key differences between theories, principles, and guidelines:

Theories: High-level widely applicable and predictive frameworks to draw on during design and evaluation.

Principles: Mid-level strategies or rules to analyze and compare design alternatives.

Guidelines: Low-level focused advice about good practices and cautions against dangers.

Guidelines provide a shared language to promote consistency among multiple people in terminology usage. It is simply a set of recommendations that are there to create reliability and consistencies among a group of individuals.

-Naureen Nizam, Computer Science Professor at the University of Toronto

It is important to realize that guidelines and principles are rule of thumbs, not widely adopted standards used by the masses. Therefore, the purpose of this chapter is to propose a set of rules and recommendations from the significant trends in API design that we have seen emerge in the past couple of years, and leverage them when it comes to designing and developing our own RESTful APIs.

CSCC10H3 Human-Computer Interaction
Professor Naureen Nizam