Skip to content
cccskills
FreePublished on GitHub

api-versioning

Version REST and GraphQL APIs. Use when a user asks to version an API, handle breaking changes, implement API deprecation, manage multiple API versions, or design an API evolution strategy.

The English summary is being prepared. Showing the original description.

TerminalSkills/skills
See how to install

Files included (2)

  • SKILL.md4.0 KB
  • _scores.json1.5 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

API Versioning

Overview

APIs evolve, but breaking changes break clients. This skill covers versioning strategies (URL path, headers, query params), deprecation workflows, backwards-compatible changes, and migration patterns for REST and GraphQL APIs.

Instructions

Step 1: URL Path Versioning (Recommended)

// routes/v1/projects.ts — Version 1 routes
import { Router } from 'express'

const v1Router = Router()

v1Router.get('/projects', async (req, res) => {
  const projects = await db.project.findMany()
  // V1 returns flat array
  res.json(projects)
})

// routes/v2/projects.ts — Version 2 with pagination
const v2Router = Router()

v2Router.get('/projects', async (req, res) => {
  const { cursor, limit = 20 } = req.query
  const projects = await db.project.findMany({
    take: Number(limit) + 1,
    cursor: cursor ? { id: String(cursor) } : undefined,
  })

  const hasMore = projects.length > Number(limit)
  if (hasMore) projects.pop()

  // V2 returns paginated envelope
  res.json({
    data: projects,
    pagination: {
      nextCursor: hasMore ? projects[projects.length - 1].id : null,
      hasMore,
    },
  })
})

// app.ts — Mount versions
app.use('/v1', v1Router)
app.use('/v2', v2Router)

Step 2: Backwards-Compatible Changes

These changes are SAFE (no version bump needed):

  • Adding new optional fields to responses
  • Adding new endpoints
  • Adding new optional query parameters
  • Adding new enum values (if clients handle unknown values)

These changes REQUIRE a new version:

  • Removing or renaming fields
  • Changing field types
  • Making optional fields required
  • Changing response structure (array → object)
  • Changing authentication scheme
// Adding a field is backwards-compatible
// V1 response: { id, name, status }
// V1.1 response: { id, name, status, taskCount }  ← safe, old clients ignore new field

// Changing structure is BREAKING
// V1 response: [{ id, name }]
// V2 response: { data: [{ id, name }], pagination: {} }  ← new version required

Step 3: Deprecation Headers

// middleware/deprecation.ts — Warn clients about deprecated versions
export function deprecationMiddleware(version: string, sunsetDate: string) {
  return (req, res, next) => {
    res.set('Deprecation', 'true')
    res.set('Sunset', sunsetDate)                // RFC 8594
    res.set('Link', `</v2${req.path}>; rel="successor-version"`)
    console.log(`[DEPRECATION] ${req.method} /v${version}${req.path} from ${req.ip}`)
    next()
  }
}

// Usage
app.use('/v1', deprecationMiddleware('1', 'Sat, 01 Jun 2026 00:00:00 GMT'), v1Router)

Step 4: API Changelog

# API Changelog

## v2.0.0 (2025-03-01)
### Breaking Changes
- `GET /projects` now returns paginated response `{ data: [], pagination: {} }`
- Removed `GET /projects/all` (use pagination instead)

### Migration Guide
- Update response parsing to read `response.data` instead of `response` directly
- Implement cursor-based pagination for large datasets
- v1 sunset date: June 1, 2026

## v1.3.0 (2025-02-15)
### Added
- `taskCount` field in project responses
- `GET /projects/{id}/activity` endpoint

Guidelines

  • URL path versioning (/v1/, /v2/) is simplest and most widely adopted.
  • Only create new major versions for breaking changes — everything else is additive.
  • Keep old versions running for 6-12 months minimum after deprecation.
  • Monitor old version usage — don't sunset until traffic is near zero.
  • Document every breaking change with a migration guide.
  • Consider API gateways (Kong, AWS API Gateway) for routing versions independently.

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Comments are published right away. Do not include personal information such as email addresses or phone numbers. Up to 2 URLs.

0 / 1,000 characters

This form is protected by reCAPTCHA, and the Google Privacy Policy and Terms of Service apply.

More skills from this repository

3dsmax-rendering

Free

Scripts and configures production rendering in Autodesk 3ds Max with the V-Ray and Corona renderers: output size and files, render elements, denoising, light mix, batch and command-line rendering, and network rendering. Use when a user asks to set up a production render, render several cameras in one batch, render from the command line or on a render farm, add render passes for compositing, or cut render time for archviz and product shots.

The English summary is being prepared. Showing the original description.

TerminalSkills/skills174Updated Oct 22, 2026

3dsmax-scripting

Free

Covers scripting Autodesk 3ds Max, the 3D modeling and rendering application, with MAXScript and Python (pymxs): scene manipulation, object creation, material assignment, camera and light setup, batch operations, and file I/O. Use when tasks involve automating repetitive 3ds Max workflows, batch processing scenes, running scripts headless with 3dsmaxbatch, creating custom tools, or scripting scene setup for archviz, product visualization, or VFX.

The English summary is being prepared. Showing the original description.

TerminalSkills/skills174Updated Oct 22, 2026

3proxy

Free

3proxy is a small open-source proxy server that runs HTTP/HTTPS, SOCKS4/5, SNI and TCP/UDP port-mapping proxies from one config file. Use when a user asks to set up an HTTP or SOCKS5 proxy, add proxy users and passwords, write 3proxy access rules, chain or rotate upstream (parent) proxies, limit bandwidth, connections or monthly traffic per user, run 3proxy in Docker, or fix a 3proxy.cfg that will not start.

The English summary is being prepared. Showing the original description.

TerminalSkills/skills174Updated Oct 22, 2026

a2a-protocol

Free

Builds Agent2Agent (A2A) servers and clients, the open protocol (originally from Google, now under the Linux Foundation) that lets AI agents from different frameworks call each other. Use when the user wants to create an A2A-compliant agent, build an Agent Card, implement task management, connect agents across frameworks, set up agent discovery, handle streaming responses, implement push notifications, or orchestrate multi-agent workflows. Trigger words: a2a, agent to agent, agent2agent, a2a protocol, a2a server, a2a client, agent card, agent interoperability, agent collaboration, multi-agent, agent discovery, a2a sdk, a2a task.

The English summary is being prepared. Showing the original description.

TerminalSkills/skills174Updated Oct 22, 2026

ab-test-setup

Free

Plans a controlled experiment (A/B test) so its result can be trusted: writes the hypothesis, picks one primary metric and the guardrails, computes sample size and run time, specifies how visitors are assigned and when exposure is logged, and reads out the result with a confidence interval. Use when someone says "set up an A/B test", "split test this page", "how many visitors do I need", "how long should the experiment run", "is this result significant", "can I stop the test early", or wants to test a headline, price, layout or onboarding change against the current version.

The English summary is being prepared. Showing the original description.

TerminalSkills/skills174Updated Oct 22, 2026

ably

Free

Ably is a hosted realtime messaging service: clients publish and subscribe to named channels over WebSockets, see who is present, replay message history, and resume after a dropped connection. Use when a user asks to "add realtime updates", "push live notifications to the browser", "show who is online", "add a chat room with typing indicators", "publish from a serverless function", or "authenticate Ably clients without exposing the API key". Covers the ably 2.x JavaScript SDK (Realtime and REST), JWT token authentication, presence, history and rewind, batch publishing, and the @ably/chat 1.x SDK.

The English summary is being prepared. Showing the original description.

TerminalSkills/skills174Updated Oct 22, 2026

See all skills by TerminalSkills

Report a problem with this skill