API Navigator Guide

Your agent for designing, documenting, and navigating REST and GraphQL APIs — helping you understand API contracts, write client integrations, and generate comprehensive API documentation.

When to Use This Agent

Choose API Navigator Guide when:

• Exploring and understanding unfamiliar REST or GraphQL APIs
• Designing API endpoints with proper HTTP methods, status codes, and response schemas
• Writing API client integrations or SDK wrappers
• Generating API documentation (OpenAPI/Swagger specs, API reference pages)
• Debugging API calls (authentication, request/response formats, error handling)

Consider alternatives when:

• You need backend implementation (controllers, services, database) — use a backend engineer agent
• You need API gateway/infrastructure setup — use a DevOps or cloud agent
• You need API performance testing — use a performance engineering agent

Quick Start

Copy
# .claude/agents/api-navigator.yml
name: API Navigator Guide
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: API design and navigation agent for REST/GraphQL endpoint design, documentation, and client integration

Example invocation:

claude "Generate an OpenAPI 3.0 spec for our user management API — it needs CRUD endpoints for users with pagination, filtering, and JWT authentication"

Core Concepts

RESTful API Design

Method	Path Pattern	Purpose	Response
GET	/api/users	List resources (paginated)	200 + array
GET	/api/users/:id	Get single resource	200 or 404
POST	/api/users	Create resource	201 + created resource
PUT	/api/users/:id	Full update	200 + updated resource
PATCH	/api/users/:id	Partial update	200 + updated resource
DELETE	/api/users/:id	Remove resource	204 (no body)

API Response Envelope

Copy
{
  "data": {
    "id": "usr_123",
    "name": "Jane Smith",
    "email": "[email protected]"
  },
  "meta": {
    "requestId": "req_abc",
    "timestamp": "2025-01-15T10:30:00Z"
  },
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 142,
    "totalPages": 8
  }
}

Configuration

Parameter	Description	Default
api_style	API paradigm (rest, graphql, grpc)	rest
spec_format	Documentation format (openapi3, asyncapi, graphql-schema)	openapi3
auth_method	Authentication method (jwt, oauth2, api-key)	jwt
pagination_style	Pagination approach (offset, cursor, keyset)	offset
versioning	API versioning strategy (url, header, query)	url

Best Practices

1. Use consistent resource naming conventions. Plural nouns for collections (/users, /orders), nested routes for relationships (/users/:id/orders), and lowercase with hyphens for multi-word resources (/user-profiles). Consistency makes APIs predictable and reduces integration friction.

2. Return appropriate HTTP status codes. Don't return 200 for everything. Use 201 for creation, 204 for deletion, 400 for validation errors, 401 for auth failures, 404 for missing resources, and 409 for conflicts. Clients depend on status codes for error handling logic.

3. Design pagination from the start. Every list endpoint should support pagination. Offset-based (?page=2&pageSize=20) is simplest; cursor-based is more performant for large datasets. Always include total count and pagination metadata in responses.

4. Version your API before the first public release. URL versioning (/v1/users) is the most visible and easiest to implement. Increment the major version only for breaking changes. Support at least one previous version during transition periods.

5. Document every endpoint with request/response examples. OpenAPI specs with example values make integration 10x faster than specs without them. Include success responses, common error responses, and authentication requirements for every endpoint.

Common Issues

API consumers break when you add required fields. Adding a required field to a request body is a breaking change for existing clients. Make new fields optional with sensible defaults, or version the endpoint. For response bodies, adding fields is safe — removing or renaming them is not.

Inconsistent error response formats across endpoints. When each endpoint returns errors differently, clients can't implement generic error handling. Standardize on a single error response format with code, message, and optional details array across all endpoints.

Pagination returns duplicate or missing items during concurrent writes. Offset-based pagination is unstable when items are inserted or deleted between page requests. For real-time data, use cursor-based pagination that anchors to a stable reference point (like a timestamp or ID) instead of an absolute offset.