It's pronounced Diane. I do data architecture, operations, and backend development. In my spare time I maintain Massive.js, a data mapper for Node.js and PostgreSQL.
Express is a good choice. It's simple and unopinionated, so you can add what you need when you need it and not get bogged down in someone else's ideal project structure.
"Someone else's ideal project structure" also describes those guidelines. That layout works for what they're doing; it may or may not work for you. Even in a bigger project, you may find it's easier to think "here are my controllers, where's the one for users?" vs "here's everything having to do with users, where's the controller?". I wouldn't be too concerned at this point. It's usually pretty obvious when something isn't working (technical or process), and then is a good time to poke around and see how other people have addressed the specific issue you're having. Source control lets you try things and roll back if they don't work so there's no reason not to experiment with various solutions when you have a problem.
If you do decide to group controllers and models together (routes should stay separate), you need to figure out what all you have. Draw up a data model, see what's in it, and divide them accordingly. Create a container directory to hold everything if you don't want it all right there in the project root. Using subdirectories or sub-subdirectories may be worthwhile to more accurately represent the model or it may be overkill; there's no way to tell without looking at it, and it's mostly a matter of taste.
Structuring the API is a different matter: there are rules to follow. If someone needs to see a list of users, there should be a GET route on /users/. If they can act on a specific user, there should be appropriate GET, PUT, POST, and DELETE routes on /users/:id. I'm not sure if that's what you're asking though, or if you're more interested in the project layout.
For versioning: structure doesn't really matter. Use npm version (or something like standard-version) to cut and tag releases. If your data model changes between releases, which it more than likely will, you'll need something to handle upgrading data. The key word to look for here is "migration", plus Node and MongoDB since there are many, many migration frameworks for everything and every database.
For the first half of your response, you got what I meant by "structuring". I am more interested in the project layout than REST principles itself.
As for the versioning, what I meant was the api.example.com/v1 vs api.example.com/v2 how do you usually handle that? Is there a recommended project layout when preparing for this? Do you have models/v1/, models/v2 or something?
What you said makes so much sense. There is some kind of paradox in these good practices. So it's really a matter of taste and what my API is for then...
I have one last question. You mentioned that I could create a container folder for everything (this is what I want instead of leaving them to the project root), is there a naming standard for such folder? For example, the dist or build folders have a naming convention for the final build of the app. I know it's a trifle, but I want to adapt™ to the javascript nomenclature as early as possible.
It's pronounced Diane. I do data architecture, operations, and backend development. In my spare time I maintain Massive.js, a data mapper for Node.js and PostgreSQL.
I've never had to worry about supporting multiple versions of a REST API at the same time, and I favor data access without models in JavaScript so that in particular is a bit of a moot point personally. I would try to avoid versioning models if at all possible simply because more code = more points of failure. There's no way around versioning routes because they have to do different things, but it should be possible to do those things with the same models even if you have to do a little fine-tuning here & there in the route code. If your schema is changing radically enough that that isn't practical, you probably have two different applications instead of two API versions. Unless you're tied into it for business reasons, such as "being Facebook", in which case all bets are off.
The conventional container folder name is "lib" in Node, although you'll occasionally see "src" instead.
Express is a good choice. It's simple and unopinionated, so you can add what you need when you need it and not get bogged down in someone else's ideal project structure.
"Someone else's ideal project structure" also describes those guidelines. That layout works for what they're doing; it may or may not work for you. Even in a bigger project, you may find it's easier to think "here are my controllers, where's the one for users?" vs "here's everything having to do with users, where's the controller?". I wouldn't be too concerned at this point. It's usually pretty obvious when something isn't working (technical or process), and then is a good time to poke around and see how other people have addressed the specific issue you're having. Source control lets you try things and roll back if they don't work so there's no reason not to experiment with various solutions when you have a problem.
If you do decide to group controllers and models together (routes should stay separate), you need to figure out what all you have. Draw up a data model, see what's in it, and divide them accordingly. Create a container directory to hold everything if you don't want it all right there in the project root. Using subdirectories or sub-subdirectories may be worthwhile to more accurately represent the model or it may be overkill; there's no way to tell without looking at it, and it's mostly a matter of taste.
Structuring the API is a different matter: there are rules to follow. If someone needs to see a list of users, there should be a GET route on
/users/. If they can act on a specific user, there should be appropriate GET, PUT, POST, and DELETE routes on/users/:id. I'm not sure if that's what you're asking though, or if you're more interested in the project layout.For versioning: structure doesn't really matter. Use
npm version(or something like standard-version) to cut and tag releases. If your data model changes between releases, which it more than likely will, you'll need something to handle upgrading data. The key word to look for here is "migration", plus Node and MongoDB since there are many, many migration frameworks for everything and every database.Hi Dian! 🤗 Thank you very much for your answer!
For the first half of your response, you got what I meant by "structuring". I am more interested in the project layout than REST principles itself.
As for the versioning, what I meant was the
api.example.com/v1vsapi.example.com/v2how do you usually handle that? Is there a recommended project layout when preparing for this? Do you havemodels/v1/,models/v2or something?What you said makes so much sense. There is some kind of paradox in these good practices. So it's really a matter of taste and what my API is for then...
I have one last question. You mentioned that I could create a container folder for everything (this is what I want instead of leaving them to the project root), is there a naming standard for such folder? For example, the
distorbuildfolders have a naming convention for the final build of the app. I know it's a trifle, but I want to adapt™ to the javascript nomenclature as early as possible.Again, thank you for your response!
I've never had to worry about supporting multiple versions of a REST API at the same time, and I favor data access without models in JavaScript so that in particular is a bit of a moot point personally. I would try to avoid versioning models if at all possible simply because more code = more points of failure. There's no way around versioning routes because they have to do different things, but it should be possible to do those things with the same models even if you have to do a little fine-tuning here & there in the route code. If your schema is changing radically enough that that isn't practical, you probably have two different applications instead of two API versions. Unless you're tied into it for business reasons, such as "being Facebook", in which case all bets are off.
The conventional container folder name is "lib" in Node, although you'll occasionally see "src" instead.
All points taken. Thank you! 👏👏