API Design and Code Structure
Use JSON as the Main Format
By this point, if you've read chapter 3 of this book, it should be obvious that we will only be supporting JSON in our API. Not only does GitHub and various other companies only support JSON, it would also create additional and unnecessary work for us if we were to support another format like XML ourselves. Hence, we will no JSON, yay!
Deciding on the Versioning Strategy
As stated previously, we will be picking the most simple API versioning strategy and we will be going with the URI prefixing method of putting api/v1 in our routes.
Global Response Message (Success and Errors)
As mentioned in chapter 3 of Representational Design, we should be following a "Using a Consistently Wrapped Response".
Being Pragmatic and Breaking (some) Rules
HATEOAS
In chapter 2 of Pragmatic REST vs Dogmatic REST, we stated that we will pragmatic with our approach as opposed to dogmatic. This means that we will not be purists and adhere to all of the guidelines that make our API RESTful. This means we will NOT be creating a hypermedia-friendly REST API, but if you want to do so, you may check out the bonus chapter of the book.
Cookies-based Authentication
Fielding stated in his dissertation that using cookies actually "violates REST". Again, we are trying to be pragmatic, so we will be using cookie-based authentication in our application, you may use other forms of authentication, but for the purpose of this book, we will be using cookies.
Keeping in mind of Guidelines over Principles and Theories
As a general precaution, we will be applying as much of the guidelines from chapter 3, but we will not be enforcing every single guideline. Keep in mind that:
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.
-Professor Naureen Nizam at the University of Toronto
A good example of this is Guideline #1: Consider Using An Application-Specific Media Type from chapter 3, Metadata Design. Why? Because it would be an overkill to submit your custom vendor data type to https://www.iana.org/assignments/media-types/media-types.xhtml, because even a company such as GitHub has yet to be approved of their custom vendor data type.
Overall Code Structure
If you recall, in JavaScript/Node.js land, structure has become a big problem in our community. However, there are a ton of pre-made boilerplate starter kits available for our needs.
You can find a list of them here in this article:
These "Express Boilerplates" provide a nice foundation for starting a project in the right way. The best boilerplate start that I have seen is https://github.com/hagopj13/node-express-boilerplate. It provides a bunch of pre-configured out-of-the-box features already baked into the repository. Features such as a global error handler, a validation library, a good authentication and authorization starter kit, and many more.
We will be using my own custom setup, but feel free to change it up to your own accord, or pull in anything else as you see fit.
Last updated
