MunchPay Node API - Apply semantic versioning

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.

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 to align until this step.

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
• 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)

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 :

yarn version

• 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.

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]

// 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 → Increment patch version → Update documentation (README in our case) → Deploy the changes
• Run

yarn version

• Type version as: 1.0.1. Press enter to update the version.
• Modify README.md accordingly.
• Once version is updated you can ping base API to check latest API version. localhost:8080

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 → Increment minor version → Update documentation (README in our case) → Deploy the changes

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 → Increment major version → Update documentation (README in our case) → 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.

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.

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. 🎯

Tirth Patel, signing off! 🫡