Skip to content

api-versioning-strat.md

Latest commit

 

History

History
106 lines (67 loc) · 3.4 KB

api-versioning-strat.md

File metadata and controls

106 lines (67 loc) · 3.4 KB

API Versioning and Deployment Strategy

Introduction

As a backend developer, it's important to have clear documentation of your API architecture and versioning strategy. This document outlines a versioning and deployment approach that can be followed to manage different versions of your API effectively. The approach described here utilizes branches and merges to handle versioning and production deployment.

1. Initial Setup

1.1. Create a Git repository for your API project. 1.2. Create a development branch, commonly named "dev," which will serve as the main development branch for ongoing work.

2. Versioning Scheme

2.1. The versioning scheme used here is based on semantic versioning (MAJOR.MINOR.PATCH). Each component represents the following:

  • MAJOR: Significant changes that are not backward compatible.
  • MINOR: Additions of new features in a backward-compatible manner.
  • PATCH: Bug fixes or backward-compatible changes.

3. Version Branches

3.1. Create a version branch for each major version of the API. For example:

  • v1: The branch representing major version 1.
  • v2: The branch representing major version 2.

4. Working on a Specific Version

4.1. Create a branch for the specific version you want to work on, based on the previous version branch. For example:

  • Create v1 branch from the dev branch:

    git checkout -b v1 dev

  • Create v2 branch from the v1 branch:

    git checkout -b v2 v1

5. Development Workflow

5.1. Checkout the branch corresponding to the specific version you are working on.

git checkout v1

5.2. Implement and test the desired changes in the version branch. 5.3. Commit and push your changes to the version branch.

git commit -m "Implemented feature X"
git push origin v1

5.4. Test the changes thoroughly in the version branch to ensure they meet the desired quality and functionality.

6. Merging to the Main Version Branch

6.1. Once the changes in a specific version branch (e.g., v1) are tested and ready, merge them into the corresponding main version branch (e.g., dev).

  • Merge v1 into dev:

    git checkout dev
git merge v1

6.2. The dev branch represents the latest development version of the API.

7. Handling Post-Production Changes

7.1. If requests for changes are received after pushing a specific version (e.g., v1) to production, create a new version branch for the next iteration of changes. For example:

  • v1.1.0: The branch representing version 1.1.0.

    git checkout -b v1.1.0 v1

7.2. Repeat the development workflow (steps 5 and 6) for the new version branch. 7.3. Merge the changes from the new version branch (e.g., v1.1.0) into the main version branch (e.g., v1) once the changes are tested and ready.

git checkout v1
git merge v1.1.0

8. Handling Major Version Updates

8.1. When it's time to introduce a major version update, create a new version branch (e.g., v2) from the previous main version branch (e.g., v1).

git checkout -b v2 v1

8.2. Follow the same workflow as mentioned above (steps 5 to 7) for the new major version.

9. Deployment

9.1. The dev branch represents the ongoing development version. 9.2. The main version branches (e.g., v1, v2) represent stable versions that are ready for production. 9.3. Deploy the latest stable version branch to the production environment.