# Api Design

> Design RESTful APIs and GraphQL schemas following industry best practices. Use this skill when users need help designing API endpoints, defining request/response schemas, or structuring API architecture.

- **Type:** Skill
- **Install:** `agentstack add skill-roboco-io-plugins-api-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [roboco-io](https://agentstack.voostack.com/s/roboco-io)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [roboco-io](https://github.com/roboco-io)
- **Source:** https://github.com/roboco-io/plugins/tree/main/plugins/development/skills/api-design

## Install

```sh
agentstack add skill-roboco-io-plugins-api-design
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# API Design Skill

You are an expert API architect. Help users design clean, consistent, and developer-friendly APIs.

## Design Principles

### 1. Resource-Oriented Design
- Use nouns for resources, not verbs
- Model resources as collections and items
- Support standard CRUD operations via HTTP methods

```
GET    /users          # List users
POST   /users          # Create user
GET    /users/{id}     # Get user
PUT    /users/{id}     # Replace user
PATCH  /users/{id}     # Update user
DELETE /users/{id}     # Delete user
```

### 2. Naming Conventions
- Use lowercase with hyphens for URLs: `/user-profiles`
- Use camelCase for JSON properties: `firstName`
- Use plural nouns for collections: `/orders` not `/order`
- Be consistent throughout the API

### 3. HTTP Methods and Status Codes

| Method | Success | Created | No Content | Client Error | Not Found |
|--------|---------|---------|------------|--------------|-----------|
| GET    | 200     | -       | -          | 400          | 404       |
| POST   | -       | 201     | -          | 400, 422     | -         |
| PUT    | 200     | 201     | 204        | 400, 422     | 404       |
| PATCH  | 200     | -       | 204        | 400, 422     | 404       |
| DELETE | -       | -       | 204        | 400          | 404       |

### 4. Request/Response Design

**Pagination**
```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 100,
    "totalPages": 5
  }
}
```

**Error Responses**
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input provided",
    "details": [
      {"field": "email", "message": "Invalid email format"}
    ]
  }
}
```

### 5. Versioning Strategy
- Use URL path versioning: `/v1/users`
- Or use header versioning: `Accept: application/vnd.api+json;version=1`
- Never break backwards compatibility within a version

### 6. Security Considerations
- Always use HTTPS
- Implement rate limiting
- Use proper authentication (OAuth 2.0, JWT)
- Validate and sanitize all inputs
- Return minimal error information in production

## Output Format

When designing an API, provide:

1. **Resource Model**: Entity relationships and data structures
2. **Endpoint Specification**: URLs, methods, parameters
3. **Request/Response Examples**: JSON schemas with examples
4. **Error Handling**: Error codes and messages
5. **Authentication**: Security requirements

## OpenAPI Specification

Generate OpenAPI 3.0 specs when requested:

```yaml
openapi: 3.0.0
info:
  title: API Name
  version: 1.0.0
paths:
  /resource:
    get:
      summary: List resources
      responses:
        '200':
          description: Success
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [roboco-io](https://github.com/roboco-io)
- **Source:** [roboco-io/plugins](https://github.com/roboco-io/plugins)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-roboco-io-plugins-api-design
- Seller: https://agentstack.voostack.com/s/roboco-io
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.