afrexai-api-architect

# API Architect — Full Lifecycle API Development

Design, build, test, document, secure, and monitor production-grade APIs. Not just curl commands — a complete engineering methodology.

## When to Use

- Designing a new API (REST, GraphQL, or gRPC)
- Reviewing an existing API for quality, consistency, or security
- Generating or validating OpenAPI/Swagger specs
- Building comprehensive test suites (unit, integration, contract, load)
- Debugging production API issues
- Planning API versioning and deprecation
- Setting up monitoring, rate limiting, and error handling

---

## Phase 1: API Design

### Design-First Approach

Always design before coding. The spec IS the contract.

#### Resource Modeling

Map your domain to resources using this template:

```yaml
# api-design.yaml
service: order-management
base_path: /api/v1
resources:
  - name: orders
    path: /orders
    description: Customer purchase orders
    identifier: order_id (UUID)
    parent: null
    operations: [list, create, get, update, cancel]
    sub_resources:
      - name: line_items
        path: /orders/{order_id}/items
        operations: [list, add, update, remove]
      - name: payments
        path: /orders/{order_id}/payments
        operations: [list, create, get, refund]
    states: [draft, confirmed, processing, shipped, delivered, cancelled]
    transitions:
      - from: draft → to: confirmed (action: confirm)
      - from: confirmed → to: processing (action: process)
      - from: processing → to: shipped (action: ship)
      - from: shipped → to: delivered (action: deliver)
      - from: [draft, confirmed] → to: cancelled (action: cancel)
```

#### Naming Conventions Checklist

| Rule | Good | Bad |
|------|------|-----|
| Plural nouns for collections | `/users` | `/user`, `/getUsers` |
| Kebab-case for multi-word | `/line-items` | `/lineItems`, `/line_items` |
| No verbs in URLs | `POST /orders` | `/createOrder` |
| Nest for ownership | `/users/123/orders` | `/orders?user=123` (for prima...

# AfrexAI API Architect 🔌

The complete API development lifecycle skill — from design through deployment, monitoring, and versioning.

## What This Does

Turns your AI agent into a senior API engineer. Not just curl commands — a full methodology:

- **Design**: Resource modeling, naming conventions, status code decision trees
- **Spec**: OpenAPI 3.1 generation with quality scoring (0-20 checklist)
- **Build**: Validation layers, error codes, idempotency, rate limiting patterns
- **Test**: Test pyramid, per-endpoint checklists, contract testing, curl recipes
- **Secure**: 30+ point security audit, CORS config, auth patterns
- **Version**: Strategy decision matrix, deprecation playbook, migration templates
- **Monitor**: Metrics dashboard, structured logging, health checks
- **Review**: 100-point API quality rubric across 6 dimensions

## Install

```bash
clawhub install afrexai-api-architect
```

## Quick Start

Tell your agent:
- *"Design a REST API for an order management system"*
- *"Review this API for quality and security issues"*
- *"Generate an OpenAPI spec for my user service"*
- *"Write comprehensive tests for the POST /orders endpoint"*
- *"Security audit our payment API"*

## What Makes This Different

Most API skills give you curl examples. This gives you:
- A **design-first methodology** (spec before code)
- **Decision matrices** (pagination type, versioning strategy, status codes)
- **Scoring rubrics** (spec quality 0-20, API quality 0-100)
- **Production patterns** (idempotency, rate limiting, webhook design)
- **GraphQL guidance** with anti-pattern detection
- **Edge case handling** (timezones, concurrent updates, eventual consistency)

## ⚡ Level Up

Want industry-specific API patterns? Our context packs include API design guidance tailored to your vertical:

- **SaaS Context Pack** — Multi-tenant API design, subscription billing APIs
- **Fintech Context Pack** — Payment processing, PSD2 compliance, ledger APIs
- **Healthcare Context Pack** — FHIR/...