REST API Skill

Provides comprehensive REST API design and implementation capabilities for the Golden Armada AI Agent Fleet Platform.

When to Use This Skill

Activate this skill when working with:

API endpoint design
HTTP request/response handling
API authentication
OpenAPI documentation
API testing

REST API Design Principles

Resource Naming

```

Good - nouns, plural

GET /agents GET /agents/{id} POST /agents PUT /agents/{id} DELETE /agents/{id}

Nested resources

GET /agents/{id}/tasks POST /agents/{id}/tasks

Bad - verbs, actions

GET /getAgents POST /createAgent ```

HTTP Methods

Method	Usage	Idempotent
GET	Read resource	Yes
POST	Create resource	No
PUT	Replace resource	Yes
PATCH	Partial update	No
DELETE	Delete resource	Yes

Status Codes

```

Success

200 OK - Successful GET, PUT, PATCH 201 Created - Successful POST 204 No Content - Successful DELETE

Client Errors

400 Bad Request - Validation error 401 Unauthorized - Authentication required 403 Forbidden - Not permitted 404 Not Found - Resource not found 409 Conflict - Duplicate/conflict 422 Unprocessable - Semantic validation error

Server Errors

500 Internal Error - Server error 502 Bad Gateway - Upstream error 503 Service Unavailable - Temporary overload ```

API Implementation (FastAPI)

```python from fastapi import FastAPI, HTTPException, Query, Path, Depends, status from typing import List, Optional from pydantic import BaseModel, Field

app = FastAPI(title="Golden Armada API", version="1.0.0")

Models

class AgentCreate(BaseModel): name: str = Field(..., min_length=1, max_length=100) type: str = Field(..., pattern="^(claude|gpt|gemini)$")

class AgentResponse(BaseModel): id: str name: str type: str status: str created_at: datetime

Endpoints

@app.get("/agents", response_model=List[AgentResponse]) async def list_agents( skip: int = Query(0, ge=0), limit: int = Query(100, ge=1, le=1000), status: Optional[str] = Query(None) ): """List all agents with pagination and filtering.""" return await agent_service.list(skip=skip, limit=limit, status=status)

@app.get("/agents/{agent_id}", response_model=AgentResponse) async def get_agent(agent_id: str = Path(..., description="Agent ID")): """Get a specific agent by ID.""" agent = await agent_service.get(agent_id) if not agent: raise HTTPException(status_code=404, detail="Agent not found") return agent

@app.post("/agents", response_model=AgentResponse, status_code=201) async def create_agent(agent: AgentCreate): """Create a new agent.""" return await agent_service.create(agent)

@app.put("/agents/{agent_id}", response_model=AgentResponse) async def update_agent(agent_id: str, agent: AgentCreate): """Replace an existing agent.""" existing = await agent_service.get(agent_id) if not existing: raise HTTPException(status_code=404, detail="Agent not found") return await agent_service.update(agent_id, agent)

@app.delete("/agents/{agent_id}", status_code=204) async def delete_agent(agent_id: str): """Delete an agent.""" deleted = await agent_service.delete(agent_id) if not deleted: raise HTTPException(status_code=404, detail="Agent not found") ```

Authentication

JWT Authentication

```python from fastapi import Depends, HTTPException, status from fastapi.security import OAuth2PasswordBearer from jose import JWTError, jwt

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

async def get_current_user(token: str = Depends(oauth2_scheme)): credentials_exception = HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="Could not validate credentials", headers={"WWW-Authenticate": "Bearer"}, ) try: payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM]) user_id: str = payload.get("sub") if user_id is None: raise credentials_exception except JWTError: raise credentials_exception return await get_user(user_id)

Protected endpoint

@app.get("/protected") async def protected_route(user: User = Depends(get_current_user)): return {"user": user.email} ```

API Key Authentication

```python from fastapi.security import APIKeyHeader

api_key_header = APIKeyHeader(name="X-API-Key")

async def verify_api_key(api_key: str = Depends(api_key_header)): if api_key != VALID_API_KEY: raise HTTPException(status_code=403, detail="Invalid API key") return api_key ```

Error Handling

```python class ErrorResponse(BaseModel): error: str message: str details: Optional[dict] = None

@app.exception_handler(ValueError) async def value_error_handler(request, exc): return JSONResponse( status_code=400, content=ErrorResponse( error="validation_error", message=str(exc) ).dict() )

@app.exception_handler(Exception) async def general_exception_handler(request, exc): return JSONResponse( status_code=500, content=ErrorResponse( error="internal_error", message="An unexpected error occurred" ).dict() ) ```

API Testing with curl

```bash

GET

curl -X GET "http://localhost:8000/agents"
-H "Authorization: Bearer TOKEN"

POST

curl -X POST "http://localhost:8000/agents"
-H "Content-Type: application/json"
-H "Authorization: Bearer TOKEN"
-d '{"name": "agent-1", "type": "claude"}'

PUT

curl -X PUT "http://localhost:8000/agents/123"
-H "Content-Type: application/json"
-d '{"name": "updated-agent", "type": "claude"}'

DELETE

curl -X DELETE "http://localhost:8000/agents/123"
-H "Authorization: Bearer TOKEN" ```

OpenAPI Documentation

```python from fastapi import FastAPI

app = FastAPI( title="Golden Armada API", description="AI Agent Fleet Platform API", version="1.0.0", docs_url="/docs", redoc_url="/redoc", openapi_url="/openapi.json" )

Access documentation at:

- Swagger UI: http://localhost:8000/docs

- ReDoc: http://localhost:8000/redoc

- OpenAPI JSON: http://localhost:8000/openapi.json

```

restapi