API Primer — Versioning APIs

  • Path parameter
  • Query parameter
  • Headers
  • Payload: Request/Response
  • Database schema changes
  • Change in business logic like new integration or new validations
  • External dependencies (APIs, etc.) change
  • Endpoint to be changed (extremely rare)

Why versioning

  • Time to integrate
  • Deployment dependencies



Maintainable database changes


  • Feature Flags
  • New versions via version in the path parameter — “v1”, “v2” so on

Impact on application code

  • com.company.api.v1.controller
  • com.company.api.v1.dto
  • com.company.api.v1.dto.mapper [ DTO to Model mapping. Idea being service layer only deals with Models ]
  • com.company.api.v1.dto.validator [ input sanitization and validation ]
  • com.company.service [ business rules/validations and persistence logic ]
  • com.company.dao
  • com.company.model
  • com.company.api.v[n].controller
  • com.company.api.v[n].dto
  • com.company.api.v[n].dto.mapper
  • com.company.api.v1.dto.validator
  • add to current model
  • extend current model for the next version
  • create a new package and model
  • add to same function: especially applicable if we have feature flag protected changes
  • create a new function in same Service class
  • create a new package/class to map to v2 packages in other layers

Clean up





Principal Architect @ Persistent Systems Limited

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Leveraging Browser Caching

Checklist for getting an internship as a Software Engineer.

3rd Month Milestone: Building A Routine

A goal journal with paper clips, cup of coffee and watch

Tagging Struct fields in Go

Basic Kubernetes Components

Summarizing Stand-up Calls: Experiments using GPT3 and Google STT ( Part 1)

Discover and Unleash Local Solutions to Chronic Problems with Discovery & Action Dialogue

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Prashant Prasannakumaran

Prashant Prasannakumaran

Principal Architect @ Persistent Systems Limited

More from Medium

Effective Session Management using Supertokens

Choosing between monolithic and microservices architectures

Getting Started with Microservices

Getting Started With Version Control Systems -A practical approach on git