Marketplace api-design

Design RESTful and GraphQL APIs following best practices. Use when creating new APIs, refactoring existing endpoints, or documenting API specifications. Handles OpenAPI, REST, GraphQL, versioning.

install

source · Clone the upstream repo

git clone https://github.com/aiskillstore/marketplace

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/aiskillstore/marketplace "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/supercent-io/api-design" ~/.claude/skills/aiskillstore-marketplace-api-design-ff98cf && rm -rf "$T"

manifest: skills/supercent-io/api-design/SKILL.md

source content

API Design

When to use this skill

Designing new REST APIs
Creating GraphQL schemas
Refactoring API endpoints
Documenting API specifications
API versioning strategies
Defining data models and relationships

Instructions

Step 1: Define API requirements

Identify resources and entities
Define relationships between entities
Specify operations (CRUD, custom actions)
Plan authentication/authorization
Consider pagination, filtering, sorting

Step 2: Design REST API

Resource naming:

Use nouns, not verbs:
```
/users
```
not
```
/getUsers
```
Use plural names:
```
/users/{id}
```
Nest resources logically:
```
/users/{id}/posts
```
Keep URLs short and intuitive

HTTP methods:

```
GET
```
: Retrieve resources (idempotent)
```
POST
```
: Create new resources
```
PUT
```
: Replace entire resource
```
PATCH
```
: Partial update
```
DELETE
```
: Remove resources (idempotent)

Response codes:

```
200 OK
```
: Success with response body
```
201 Created
```
: Resource created successfully
```
204 No Content
```
: Success with no response body
```
400 Bad Request
```
: Invalid input
```
401 Unauthorized
```
: Authentication required
```
403 Forbidden
```
: No permission
```
404 Not Found
```
: Resource doesn't exist
```
409 Conflict
```
: Resource conflict
```
422 Unprocessable Entity
```
: Validation failed
```
500 Internal Server Error
```
: Server error

Example REST endpoint:

GET    /api/v1/users           # List users
GET    /api/v1/users/{id}      # Get user
POST   /api/v1/users           # Create user
PUT    /api/v1/users/{id}      # Update user
PATCH  /api/v1/users/{id}      # Partial update
DELETE /api/v1/users/{id}      # Delete user

Step 3: Request/Response format

Request example:

POST /api/v1/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin"
}

Response example:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/123

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Step 4: Error handling

Error response format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input provided",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Step 5: Pagination

Query parameters:

GET /api/v1/users?page=2&limit=20&sort=-created_at&filter=role:admin

Response with pagination:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 100,
    "pages": 5
  },
  "links": {
    "self": "/api/v1/users?page=2&limit=20",
    "first": "/api/v1/users?page=1&limit=20",
    "prev": "/api/v1/users?page=1&limit=20",
    "next": "/api/v1/users?page=3&limit=20",
    "last": "/api/v1/users?page=5&limit=20"
  }
}

Step 6: Authentication

Options:

JWT (JSON Web Tokens)
OAuth 2.0
API Keys
Session-based

Example with JWT:

GET /api/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Step 7: Versioning

URL versioning (recommended):

/api/v1/users
/api/v2/users

Header versioning:

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

Step 8: Documentation

Create OpenAPI 3.0 specification:

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
        created_at:
          type: string
          format: date-time
    UserCreate:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
        email:
          type: string
          format: email

Best practices

Consistency: Use consistent naming, structure, and patterns
Versioning: Always version your APIs from the start
Security: Implement authentication and authorization
Validation: Validate all inputs on the server side
Rate limiting: Protect against abuse
Caching: Use ETags and Cache-Control headers
CORS: Configure properly for web clients
Documentation: Keep docs up-to-date with code
Testing: Test all endpoints thoroughly
Monitoring: Log requests and track performance

Common patterns

Filtering:

GET /api/v1/users?role=admin&status=active

Sorting:

GET /api/v1/users?sort=-created_at,name

Field selection:

GET /api/v1/users?fields=id,name,email

Batch operations:

POST /api/v1/users/batch
{
  "operations": [
    {"action": "create", "data": {...}},
    {"action": "update", "id": 123, "data": {...}}
  ]
}

GraphQL alternative

If REST doesn't fit, consider GraphQL:

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
  createdAt: DateTime!
}

type Query {
  users(page: Int, limit: Int): [User!]!
  user(id: ID!): User
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
}