Chapter 3: RESTful API Design Guidelines and "Best Practices"

In this chapter, we will introduce how to properly design a RESTful web API. We'll be going over the best practices when designing URIs, representations, metadata, versioning, and more. The focus of this chapter is not to enforce the absolute "best practices", but rather show pragmatic examples that the community has learned in the past decade.

The set of guidelines and best practices come from notable books such as REST API Design Rulebook by Mark Masse, RESTful Web Services Cookbook by Subbu Allamaraju, and The REST API Design Handbook by George Reese; 3 books by incredible authors with a wide array of experiences in building APIs. Other resources come from large tech companies such as Microsoft, Google, and Zalando who have publicly shared their own REST API guidelines. And of course, the remaining best practices and guidelines come from me, my own personal experiences and what I learned in the my career.

The point of this chapter is to depict what has been considered "best practices" deemed by various different sources. This is so that we may use what others have discovered from their own real world experiences and apply them to our API design.