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.

// 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