MunchPay Node API - Apply semantic versioning
Tags: node, express, programming, beginners
Published: 2022-12-01 18:29:53

## Recalling SemVer

- A quick revision of the Semantic Version. It consists of 3 sections.

```
MAJOR.MINOR.PATCH
```

**MAJOR:** It represents the major version of the app. Any incompatible change, API modification, or such changes are handled under this number.

**MINOR:** When you add new functionality in a backward compatible manner is introduced in the product. Any improvement (like performance, optimization, etc) can be covered under this.

**PATCH:** As the name suggests it is reserved for bug fixes internal to the system/product. Note that these bug fixes should be backward compatible.

<hr />

## Let's make MunchPay API 💰

- Let's make a basic payment API called as MunchPay. This API will have just 2 routes: 1) Get payment methods 2) Make payment
- To get started we need to have a Node App which can serve as an API server. For sake of this blog, I've used Express JS. These are the checkpoints that should be ready to move ahead.
   - Create a Node project
   - Install the following npm packages: `express, nodemon`
   - Write boilerplate for express server
   - Create 1 GET route: `getPaymentMethods`
   - Create 1 POST route: `makePayment`
   - Update the scripts in package.json to spin up the server
- You can clone this repo [MunchPay API Get Started](https://github.com/tirth-2001/munchpay-api) to align until this step.

<hr />

## Deploying dev version on public 🌐

- To deploy MunchPay API, we'll use Vercel. I have mentioned a detailed guide on how to deploy the Express JS app on Vercel in this [Deploy Node JS on Vercel](https://dev.to/tirthpatel/node-js-express-app-on-vercel-develop-run-deploy-524a)
- To shorten the length of this article we're not covering each step here.
- Once API will be deployed you can see something like this. (If you don't want to deploy, running it on local server will also work)


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hqjtp0bolpqtxzzhlx69.png)

<hr />

## Release the first version 1️⃣

- Let's make this API public and release the first stable version.
- NOTE: To declare a public API we need to maintain proper documentation of what is changed in each release.
- Create a README.md file at the root of the project. This will serve as documentation of our MunchPay API. (Actual APIs use other tools like Swagger/OpenAPI etc for maintaining documentation)
- Node projects give us a nice option to manage versions of our project.
- Go to the root of the project in a terminal. And execute this command :
```bash
yarn version
```
<br />

- This will show you the current version and prompt for a new version. Enter the new version as `1.0.0`. As we're releasing for the first time, this will be the base version for our Public API.
- You will notice that the `yarn version` command will also commit the version changes.

<hr />
## Planning new patch release 🏷️
- Patch means any internal bug fixes with backward compatibility. This means this change should not break the end users' app.
- You can see `src/controllers/payment.js` file. In this initially, we've artificially set up a bug. We're using amount value from request body for currency conversion. But validation is not done if amount is not passed in body. This is a potential bug.
- Let's rectify this. Replace the function with the following function. [`controllers/payment.js`]

```javascript
// POST /makePayment
router.post('/make-payment', (req, res) => {
	const { amount, mode } = req.body

	if (!amount) {
		return res.status(400).json({
			message: 'Amount is required',
		})
	}

	const convertedAmount = convertINRToUSD(amount)
	res.json({
		message: 'Payment Successfull ✅',
		amount: convertedAmount,
		currency: 'USD',
		mode,
	})
})
```
- For PATCH the process can be something similar to this. Fix Bug &#8594;	Increment patch version &#8594;	Update documentation (README in our case) &#8594; Deploy the changes
- Run 
```bash
yarn version
```
- Type version as: `1.0.1`. Press enter to update the version.
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/heb9f7vxjnc01bxo6ktv.png)
- Modify `README.md` accordingly.
- Once version is updated you can ping base API to check latest API version. `localhost:8080`

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/py8q93hdqinvaz5jz8zc.png)



<hr />
## Deploying new minor release 🔖
- MINOR means any internal improvement with backward compatibility. So this change should not break the user's app.
- You can perform any such change in our API. Currently, all available payment methods are static. You can call another API to fetch payment methods according to the user's region.
- Once those changes are done, further process is the same as we did in deploying the PATCH version.
-  Modify code &#8594;	Increment minor version &#8594;	Update documentation (README in our case) &#8594; Deploy the changes

<hr />
## Publishing a major release ⭐
- MAJOR means a groundbreaking change that will affect end users.
- You can plan any such incompatible update in our API. Suppose you change the route name of `makePayment` API or you change the method of `getPaymentMethods` from GET to POST. (or any such change)
- Once those changes are done, further process is the same as we did in deploying the PATCH version.
-  Modify code &#8594;	Increment major version &#8594;	Update documentation (README in our case) &#8594; Deploy the changes
- **NOTE:** When we increment a major version, minor and patch values must be pointed to 0. So now your API's version will be `2.0.0`.


<hr />
## Key takeaways 📝
- We saw how to plan patch, minor and major releases based on MunchPay payment API.
- Incrementing version and reflecting changes in the documentation must be done without fail for any new release (patch, minor or major)
- Deploying our Node API and releasing it for public use.

<hr />
## Closing Comments 🙋‍♂️
- Thank you for following along with me. If you find any queries on the above-mentioned topic, please ping me in the comments.
- Knowledge spreads by sharing. So please share this article with your concerned friends.
- PS: Also, I humbly request you to write which topic you want in my next blog. I will include that in my target list. 🎯

<br />
Tirth Patel, signing off! 🫡