atelier-typescript-api-design_skill

Overview

This skill provides framework-agnostic REST API design patterns for building consistent, maintainable endpoints, error responses, pagination, and versioning. It gathers practical conventions for naming, versioning, status codes, error formats, pagination, filtering, and idempotency. Use it to align teams on predictable API behavior and reduce long-term maintenance costs.

How this skill works

The skill inspects API surface design decisions and recommends patterns: plural resource naming, URL-based versioning, RFC 7807 problem details for errors, cursor-based pagination, and consistent HTTP status usage. It outlines concrete request/response shapes, pagination and filtering query usage, idempotency handling, and timestamp formatting. Implementation snippets show how to wire routes per version, return standardized errors, and implement cursor pagination safely.

When to use it

• Designing new REST endpoints or refactoring existing APIs to be consistent
• Defining error-handling and response schemas for clients and services
• Choosing pagination strategy for large collections and performance needs
• Establishing versioning strategy for breaking changes
• Adding idempotency or timestamp conventions for transactional endpoints

Best practices

• Use plural nouns and lowercase hyphenated paths (e.g., /ledger-accounts)
• Put API version in the URL path (/api/v1/) for easy testing and caching
• Return RFC 7807 problem details for errors with type, status, detail, instance, and traceId
• Prefer cursor-based pagination for large or frequently changing datasets
• Use ISO 8601 UTC timestamps (toISOString()) and correct HTTP status codes
• Avoid unnecessary response envelopes except when returning pagination metadata

Example use cases

• Designing user and nested resource endpoints: GET /api/v1/users/:id and /api/v1/users/:id/posts
• Implementing consistent error responses for NotFound, Conflict, and ServiceUnavailable
• Switching from offset to cursor pagination for a high-volume feed
• Adding Idempotency-Key handling to POST /api/v1/transactions to prevent duplicate charges
• Versioning a breaking response change by adding /api/v2 while keeping /api/v1