⚙️ Backend Engineering · API Design

Model REST resources without leaking internals (gRPC services)

Design stable resource-oriented endpoints with deliberate error contracts and pagination.

foundation~30 minBackend EngineersAPI DevelopersPlatform Engineers

Steps

1List nouns (resources) from the domain; map verbs to HTTP methods
2Pluralize collections; nest at most one level for ownership
3Standardize errors as {code, message, details} with correct status codes
4Paginate every collection by cursor; never offset past 10k rows
5Version in the URL path from v1; document deprecation policy
6Publish an OpenAPI spec and generate clients from it
7Define proto packages with backward-compatible field numbering
8Map gRPC status codes to HTTP at the gateway

Common Pitfalls

▲RPC-in-disguise endpoints like /getUserData
▲Leaking column names and internal IDs in payloads

Commands

Install with skills CLI

$ npx skills add aniruddhaadak80/skills --skill api-design-rest-resource-modeling-rpc

Install globally

$ npx skills add aniruddhaadak80/skills --skill api-design-rest-resource-modeling-rpc -g

Tags

#rest#api#http#backend-engineering#api-design

Install this skill

$ npx skills add aniruddhaadak80/skills --skill api-design-rest-resource-modeling-rpc -a opencode

SKILL.md

# Model REST resources without leaking internals (gRPC services)

> Design stable resource-oriented endpoints with deliberate error contracts and pagination.

## When to Use This Skill

Design stable resource-oriented endpoints with deliberate error contracts and pagination.

## Steps

1. List nouns (resources) from the domain; map verbs to HTTP methods
2. Pluralize collections; nest at most one level for ownership
3. Standardize errors as {code, message, details} with correct status codes
4. Paginate every collection by cursor; never offset past 10k rows
5. Version in the URL path from v1; document deprecation policy
6. Publish an OpenAPI spec and generate clients from it
7. Define proto packages with backward-compatible field numbering
8. Map gRPC status codes to HTTP at the gateway

## Common Pitfalls

- RPC-in-disguise endpoints like /getUserData
- Leaking column names and internal IDs in payloads

View source on GitHub ↗

Design stable resource-oriented endpoints with deliberate error contracts and pagination.

⚙️ Backend Engineering·~30m

Open →

Make writes safe with idempotency keysintermediate

Accept retried mutations gracefully by keying operations so duplicates return the original result.

⚙️ Backend Engineering·~30m

Open →

Migrate API versions without breaking clientsadvanced

Run two versions in parallel, observe usage, and sunset safely with real telemetry.

⚙️ Backend Engineering·~40m

Open →