API Mock Helper

# API Mock & Sandbox Skill

Generate mock servers, stubs, fixtures, and sandbox environments for any API.

---

## Mock Strategy Selection

| Scenario | Tool / Approach |
|----------|----------------|
| Frontend dev against unbuilt backend | WireMock / Prism / MSW |
| Unit tests (in-process) | In-memory mock functions |
| Contract testing | Pact (consumer-driven contracts) |
| Postman testing | Postman Mock Server |
| Local development | Prism CLI from OpenAPI spec |
| Record & replay real API | VCR (Python/Ruby), nock recordings |

---

## WireMock Stub Definition

```json
{
  "request": {
    "method": "GET",
    "urlPathPattern": "/api/v1/users/([a-z0-9-]+)"
  },
  "response": {
    "status": 200,
    "headers": { "Content-Type": "application/json" },
    "jsonBody": {
      "id": "{{request.pathSegments.[3]}}",
      "name": "Alice Smith",
      "email": "alice@example.com",
      "created_at": "2024-01-01T00:00:00Z"
    }
  }
}
```

### WireMock Stateful Scenario
```json
[
  {
    "scenarioName": "Order flow",
    "requiredScenarioState": "Started",
    "newScenarioState": "Paid",
    "request": { "method": "POST", "url": "/api/v1/orders" },
    "response": { "status": 201, "jsonBody": { "id": "ord_123", "status": "pending" } }
  },
  {
    "scenarioName": "Order flow",
    "requiredScenarioState": "Paid",
    "request": { "method": "GET", "url": "/api/v1/orders/ord_123" },
    "response": { "status": 200, "jsonBody": { "id": "ord_123", "status": "paid" } }
  }
]
```

---

## Mock Service Worker (MSW — browser/Node.js)

```js
import { http, HttpResponse } from 'msw';

export const handlers = [
  http.get('/api/v1/users', () => {
    return HttpResponse.json({
      data: [
        { id: 'usr_1', name: 'Alice', email: 'alice@example.com' },
        { id: 'usr_2', name: 'Bob', email: 'bob@example.com' },
      ],
      pagination: { total: 2, page: 1, limit: 20 }
    });
  }),

  http.post('/api/v1/users', async ({ request }) => {
    const body = await request.json();
    return HttpResponse.json(
      { id: 'usr_new', ...body, created_at: new Date().toISOString() },
      { status: 201 }
    );
  }),

  http.get('/api/v1/users/:id', ({ params }) => {
    if (params.id === 'not-found') {
      return HttpResponse.json({ error: 'NOT_FOUND' }, { status: 404 });
    }
    return HttpResponse.json({ id: params.id, name: 'Alice' });
  }),
];
```

---

## Fixture Data Generator

```python
from faker import Faker
import uuid

fake = Faker()

def generate_user(overrides=None):
    user = {
        "id": str(uuid.uuid4()),
        "name": fake.name(),
        "email": fake.email(),
        "phone": fake.phone_number(),
        "address": {
            "street": fake.street_address(),
            "city": fake.city(),
            "country": fake.country_code()
        },
        "created_at": fake.date_time_this_year().isoformat()
    }
    return {**user, **(overrides or {})}

def generate_users(count=10):
    return [generate_user() for _ in range(count)]
```

---

## Error Scenario Stubs

Always include these error stubs for every endpoint:
```json
{ "request": { "method": "GET", "url": "/api/v1/users/error-500" },
  "response": { "status": 500, "jsonBody": { "error": "INTERNAL_ERROR" } } }

{ "request": { "method": "GET", "url": "/api/v1/users/error-401" },
  "response": { "status": 401, "jsonBody": { "error": "UNAUTHENTICATED" } } }

{ "request": { "method": "GET", "url": "/api/v1/users/error-429" },
  "response": { "status": 429,
    "headers": { "Retry-After": "30" },
    "jsonBody": { "error": "RATE_LIMIT_EXCEEDED" } } }
```

---

## Prism CLI (mock from OpenAPI spec)

```bash
# Install
npm install -g @stoplight/prism-cli

# Mock from local spec
prism mock openapi.yaml --port 4010

# Mock from URL
prism mock https://api.example.com/openapi.json

# Validate requests against spec
prism proxy https://api.example.com openapi.yaml
```

---

## After Completing the API Mocks and Stubs (as requested)

Once the API mocks output is delivered, ask the user:

"Would you like me to help in devising rate limiting strategies for these APIs? (yes/no)"

If the user says **yes**:
- Check if the api-ratelimiting-helper skill is available in the installed skills list
- If the skill **is available**:
  - Read and follow the instructions in the api-ratelimiting-helper skill
  - Use the API information output above as the input
- If the skill **is NOT available**:
  - Inform the user: "It looks like the api-ratelimiting-helper skill isn't installed. 
    You can install it and re-run.

If the user says **no**:
- End the task here

---