skills.rest
jrmatherly
jrmatherlyCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-versioning

Implement API versioning strategies for TypeScript/JavaScript and Python.

Updated Jan 30, 2026
Search Tags:#typescript#versioning#API#routing#python#deprecation#backwards-compatibility
One-click install
npx skills add https://github.com/jrmatherly/metorial-workspace --skill api-versioning-jrmatherly
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-versioning
Source: https://github.com/jrmatherly/metorial-workspace/tree/main/.github/skills/api-versioning
Command: npx skills add https://github.com/jrmatherly/metorial-workspace --skill api-versioning-jrmatherly

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

API consumers rely on stable interfaces; this Skill enables teams to implement versioning strategies that preserve backward compatibility while introducing improvements.

Core Features & Use Cases

  • URL Path Versioning: version endpoints with /v1, /v2, etc., ensuring clear migration paths.
  • Header-Based Versioning: use Accept or custom headers to select API versions without URL changes.
  • Deprecation Workflows: define a plan for sunset and migration with appropriate client communication and headers.
  • Use Case: Public APIs with external clients can migrate gradually, while internal services can route traffic to the appropriate version during rollout.

Quick Start

Install or prepare your environment with Node.js and Python, then implement versioned routes that detect version from the URL, headers, or query parameters, and route to version-specific handlers as shown in the guide.

Frequently Asked Questions about api-versioning

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I version an API without breaking existing clients?▼

You can maintain API backward compatibility by implementing URL path versioning with /v1 endpoints, or using header-based versioning with Accept headers, ensuring existing clients continue functioning while new versions roll out.

What is the difference between URL path versioning and header-based API versioning?▼

URL path versioning exposes the version in the endpoint path like /v1, while header-based versioning uses Accept or custom headers to select versions without changing URLs, keeping routing logic hidden from the client interface.

How do I set up a deprecation workflow for an old API version?▼

API deprecation workflows define a sunset plan using deprecation metadata and headers to communicate migration paths, ensuring clients receive clear timelines and guidance before the old version is permanently removed.

Does this API versioning approach work with both Python and TypeScript?▼

This API versioning approach supports both TypeScript/JavaScript and Python environments, providing version routing logic and deprecation workflows with practical example code for Node.js and Python implementations.

Can I use header-based versioning for internal services?▼

Header-based versioning works well for internal services, allowing traffic routing to appropriate versions during rollout without modifying URL structures, which is ideal for internal APIs requiring seamless version transitions.

When should I use API versioning instead of building a new endpoint?▼

API versioning is necessary when introducing improvements that break backward compatibility, allowing public APIs with external clients to migrate gradually rather than forcing immediate adoption of breaking changes.

Related Skills

Explore More Software Engineering Skills→
LevironexeLevironexe
1

Hono API

Structure Hono APIs with separated routes, services, middleware, and Zod validation.

Community
Intermediate
oborchersoborchers
28

versioning-and-evolution

Guide API versioning strategies, additive evolution, and deprecation management.

Community
Advanced
pmarashianpmarashian
2

cors-cookie-auth

Configure CORS headers for cookie authentication in API route handlers.

Community
Intermediate
pluginagentmarketplacepluginagentmarketplace
1

versioning

Implement API versioning strategies with URL path, header, or query configurations.

Community
Intermediate