Rest Expert

---
name: rest-expert
description: Use when implementing rest functionality with production-grade patterns and safeguards.
metadata:
  hermes:
    tags: [codex-agent, general]
    source: codex-field-kit/general
---

# Rest Expert

## Focus Areas

- Understanding REST architectural principles
- Designing resources and endpoints
- Using correct HTTP methods (GET, POST, PUT, DELETE, PATCH)
- Implementing HTTP status codes appropriately
- Versioning strategies for APIs
- Resource modeling and URI design
- Statelessness and its implications
- Content negotiation (media types, JSON, XML)
- Authentication and authorization in REST
- Rate limiting and throttling

## Approach

- Resource-oriented design over action-oriented endpoints
- Use "hypermedia as the engine of application state" (HATEOAS) when necessary
- Ensure all interactions are stateless
- Consistent naming conventions for endpoints
- Utilize query parameters for filtering and pagination
- Proper documentation with examples using OpenAPI/Swagger
- Secure endpoints via HTTPS only
- Handle errors through standardized error responses
- Cacheability of GET requests when applicable
- Monitoring and logging of API usage

## Quality Checklist

- Endpoints follow standardized naming conventions
- Proper use of HTTP verbs ensuring idempotency where needed
- Appropriate status codes for every possible response
- Error handling and validation are robust and descriptive
- API responses are correctly paginated
- Documentation is accurate and comprehensive
- Security practices are aligned with industry standards
- Response headers include caching directives
- Rate limits are set and communicated in headers
- Compliance with REST constraints and limitations

## Output

- A well-documented, RESTful API with a clear resource model
- Examples of requests and responses for different endpoints
- Error handling strategy with sample error messages
- Versioning strategy detailed in documentation
- Authentication and authorization setup explanations
- Detailed logging of request and response data
- Secure API endpoints with encryption in transit
- Sample client code for common tasks
- Monitoring setup details for API usage
- Guidelines for onboarding new developers to the API