api-design

name	api-design
description	Design RESTful APIs with proper routes, validation, error handling, and documentation. Use when building backend services for PSI Engine or other server applications.

🔗 API Design Skill

RESTful Conventions

Method	Path	Action
GET	/agents	List all
GET	/agents/:id	Get one
POST	/agents	Create
PUT	/agents/:id	Update
DELETE	/agents/:id	Delete

---

Response Format

Success

{
  "success": true,
  "data": {
    "id": "agent_001",
    "status": "running"
  }
}

Error

{
  "success": false,
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent with id 'xyz' not found",
    "details": {}
  }
}

Pagination

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "hasMore": true
  }
}

---

Express.js Patterns

Route Structure

// routes/agents.js
const router = express.Router();

router.get('/', listAgents);
router.get('/:id', getAgent);
router.post('/', validateAgent, createAgent);
router.put('/:id', validateAgent, updateAgent);
router.delete('/:id', deleteAgent);

module.exports = router;

Controller

async function createAgent(req, res, next) {
  try {
    const agent = await AgentService.create(req.body);
    res.status(201).json({ success: true, data: agent });
  } catch (error) {
    next(error);
  }
}

Error Handler

function errorHandler(err, req, res, next) {
  const status = err.status || 500;
  const code = err.code || 'INTERNAL_ERROR';
  
  res.status(status).json({
    success: false,
    error: {
      code,
      message: err.message,
      ...(process.env.NODE_ENV === 'dev' && { stack: err.stack })
    }
  });
}

---

Validation (Zod)

const { z } = require('zod');

const AgentSchema = z.object({
  name: z.string().min(1).max(100),
  task: z.string().min(1),
  priority: z.enum(['low', 'medium', 'high']).default('medium')
});

function validateAgent(req, res, next) {
  try {
    req.body = AgentSchema.parse(req.body);
    next();
  } catch (error) {
    res.status(400).json({
      success: false,
      error: { code: 'VALIDATION_ERROR', message: error.message }
    });
  }
}

---

Flask Patterns (Python)

from flask import Flask, jsonify, request

@app.route('/agents', methods=['POST'])
def create_agent():
    data = request.json
    
    # Validate
    if not data.get('name'):
        return jsonify(success=False, error={'code': 'VALIDATION_ERROR'}), 400
    
    # Create
    agent = agent_service.create(data)
    return jsonify(success=True, data=agent), 201

@app.errorhandler(Exception)
def handle_error(error):
    return jsonify(success=False, error={'message': str(error)}), 500

---

PSI Engine API Example

GET  /api/agents           → List all agents
POST /api/agents           → Spawn new agent
GET  /api/agents/:id       → Get agent status
POST /api/agents/:id/task  → Assign task
DELETE /api/agents/:id     → Terminate agent

GET  /api/knowledge        → Search knowledge base
POST /api/knowledge        → Add knowledge entry