API Redesign Proposal

public
example document
12 views2 comments1 review

API Redesign Proposal

This document outlines the planned changes to our v2 API, including breaking changes and migration paths.

Our v1 API has served us well, but several pain points have emerged:

  • Inconsistent naming — some endpoints use camelCase, others snake_case
  • No pagination — large collections return everything at once
  • Monolithic responses — no way to request partial data

#1. Consistent REST conventions

All endpoints will follow REST naming conventions with snake_case:

GET    /v2/deployments
GET    /v2/deployments/:id
POST   /v2/deployments
PATCH  /v2/deployments/:id
DELETE /v2/deployments/:id

#2. Cursor-based pagination

All list endpoints return paginated results:

{
  "data": ["..."],
  "cursor": "eyJpZCI6MTIzfQ",
  "has_more": true
}

#3. Deployment flow

#4. Authentication

All requests require a Bearer token:

GET /v2/deployments/:id
Authorization: Bearer {token}
PhaseTimelineAction
AnnounceWeek 1Publish migration guide
Dual-runWeeks 2-8Both v1 and v2 active
DeprecateWeek 9v1 returns deprecation headers
SunsetWeek 12v1 returns 410 Gone
  • Rate limiting strategy for v2?
  • Should we version the WebSocket API too?
  • How to handle long-running deployments during migration?