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
```