Skill: API Designer

Category: Dev Expert Version: 1.0.0 Used By: backend-nodejs, backend-python, backend-go, backend-laravel

Overview

Design consistent, RESTful APIs with proper versioning, documentation, and error handling.

1. RESTful Conventions

Method Endpoint Purpose Response

GET /users List all 200 + array

GET /users/:id Get one 200 / 404

POST /users Create 201 + created

PUT /users/:id Replace 200 / 404

PATCH /users/:id Update 200 / 404

DELETE /users/:id Delete 204 / 404

Nested Resources

GET /users/:userId/orders # User's orders POST /users/:userId/orders # Create order for user GET /users/:userId/orders/:orderId # Specific order

2. Naming Conventions

Type Convention Example

Resources Plural nouns /users , /orders

Actions Verbs (rare) /auth/login , /reports/generate

Query params snake_case ?page_size=20

Request/Response camelCase { "firstName": "John" }

3. Versioning Strategies

Strategy Example When to Use

URL Path /v1/users

Most common, clear

Header Accept: application/vnd.api+json;version=1

Clean URLs

Query /users?version=1

Simple but messy

Recommended: URL path (/api/v1/... )

4. Response Format

Success

{ "data": { "id": "123", "name": "John" }, "meta": { "timestamp": "2025-01-01T00:00:00Z" } }

List with Pagination

{ "data": [{ "id": "1" }, { "id": "2" }], "meta": { "page": 1, "pageSize": 20, "total": 100, "totalPages": 5 } }

Error

{ "error": { "code": "VALIDATION_ERROR", "message": "Invalid input", "fields": { "email": "Invalid format" } } }

5. Status Codes

Code Meaning When to Use

200 OK Successful GET/PUT/PATCH

201 Created Successful POST

204 No Content Successful DELETE

400 Bad Request Invalid input

401 Unauthorized No/invalid auth

403 Forbidden No permission

404 Not Found Resource missing

409 Conflict Duplicate/state conflict

422 Unprocessable Validation failed

429 Too Many Rate limited

500 Server Error Unexpected error

6. Pagination Patterns

Offset-based (Simple)

GET /users?page=2&page_size=20

Cursor-based (Scalable)

GET /users?cursor=eyJpZCI6MTAwfQ&limit=20

Pattern Pros Cons

Offset Simple, jump to page Slow on large datasets

Cursor Consistent, fast No page jumping

7. Filtering & Sorting

Filter

GET /users?status=active&role=admin

Sort

GET /users?sort=created_at:desc,name:asc

Search

GET /users?q=john

Combined

GET /users?status=active&sort=name:asc&page=1&page_size=20

8. API Documentation (OpenAPI)

openapi: 3.0.0 info: title: User API version: 1.0.0 paths: /users: get: summary: List users parameters: - name: page in: query schema: { type: integer, default: 1 } responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/UserList'

9. API Design Checklist

• RESTful resource naming

• Consistent response format

• Proper status codes

• Pagination for lists

• Error responses with codes

• Versioning strategy

• OpenAPI documentation

• Rate limiting headers

Best Practices

Do's

• Use plural nouns for resources

• Return created/updated resource

• Include pagination metadata

• Document with OpenAPI

• Version from day one

Don'ts

• Use verbs in resource names

• Return different formats per endpoint

• Expose internal IDs/structures

• Ignore backward compatibility

• Skip error code standards

Version: 1.0.0 | Last Updated: 2025-11-28