I have been using Node.js with Express.js for just over a year now and Typescript for 8 months building and maintaining micro services for an SME business operating globally.
The project is at: https://github.com/daveKoala/typescript-api-starter.git
Of the 1/2 dozen I’ve created from scratch each has grown in sophistication. I now know what I want for each REST api service (in no real order):
- Node.js with Express.js
- Multiple environments
- Typescript
- Unit testing (with tests alongside the code and not in ./tests/ directory)
- External cache
- A ‘developer’ mode that restarts when saving
- Debugging so I don’t have to rely on console.log
- All end points versioned and documented
- Authentication and Authorisation middleware
- Custom errors
- Re-try connections if they initially fail
- Project auto saves and lints
- A CI/CD pipeline that runs test and checks for external package vulnerabilities.
I am nearly there…
Node.js, Express.js and Typescript. Not much to say about this that has not already been said.
Multiple Environments: This is a bit trickier as conventional wisdom is that env values are not stored within the repo. This makes perfect sense, however the projects I am working with have 3 people at most and keeping the env within the private repo lets us quickly create new services and keep all settings, pipelines etc together with minimal fuss. It was a decision we made as a group 18 months ago and has paid off. I know there will be eye rolling at this tho’.
Unit Testing: I using Mocha.js and Chai.js no real reason apart from it works for me. There are 2 specific requirements. The first being that test scripts sit alongside the code being tested and the second is the option to publish test results. This project does both.
External Cache: Middleware on routes that intercepts the request, hashes the url and body to make an ID then queries the cache. A null response passes the request to the controller and caches the results.
‘Developer mode’: Easy with Nodemon and scripts within the package.json file. There are a few other useful scripts including a “lazy script” that runs tests, linting, audits and a build process.
Debugging: I’ll leave that to Visual Studio Code and commit any settings files.
All end points versioned and documented: Using Swagger and OpenDoc to create nice api docs. Added advantage is that you can link/download to the OpenDocs JSON into Postman to create collections.
Versioning: I opted for the “version via the request header” approach. Why? I like that the urls don’t change and because it is strict. Strict as in, if you fail to request a version you get feedback telling you what you need to do. The main thing about versioning is declaring a contract and sticking to it.
Authentication and Authorisation: Separate middleware that can leverage different methods specified by the project.
Custom errors: Easy enough, create meaningful error messages and responses. They also accept plugins for external logging.
Re-try connections if they initially fail: Also known as a Circuit Breaker pattern.
Project auto saves and lints: Let Visual Studio handle this and commit settings to the project.
CI/CD Pipeline: Convention over configuration and making use of files like Azure Pipelines YAML files to describe and run CI/CD processes.
This is an ongoing project and can be found at: https://github.com/daveKoala/typescript-api-starter.git