REST API Skill

Expert guidance for designing and building RESTful APIs following industry standards.

Overview

This skill extends Claude and other AI coding agents with comprehensive REST API expertise, including:

• Resource Design — Resource-oriented URLs, naming conventions, relationships
• HTTP Semantics — Correct methods, status codes, idempotency
• Error Handling — Consistent error response format, error codes
• Pagination — Cursor-based pagination (required), no offset pagination
• Idempotency — Idempotency keys for POST/PATCH requests
• Versioning — URL path, header, and query parameter strategies
• Security — Authentication methods, security headers, request tracing
• Documentation — OpenAPI 3.1 specification

Installation

RooCode

git clone https://github.com/tresic-cloud/rest-api-skill.git
cp -r rest-api-skill ~/.roo/skills/

Claude Code

git clone https://github.com/tresic-cloud/rest-api-skill.git
cp -r rest-api-skill ~/.claude/skills/

Claude.ai / Claude Desktop

1. Download this repository as a ZIP file
2. Go to Settings → Capabilities → Skills
3. Click Upload skill and select the ZIP file

GitHub Copilot

git clone https://github.com/tresic-cloud/rest-api-skill.git
cp -r rest-api-skill .github/skills/

Usage

Just ask Claude naturally—the skill activates automatically when relevant:

Try asking:

• "Design REST endpoints for a user management service"
• "What's the correct HTTP status code for this scenario?"
• "Implement cursor-based pagination for this endpoint"
• "Add idempotency key support to this POST endpoint"
• "Review this API design against REST best practices"
• "Generate OpenAPI 3.1 documentation for these endpoints"
• "What's the proper error response format?"
• "How should I version my API?"

Key Standards

Topic	Standard
Pagination	Cursor-based only (no offset)
Idempotency	Required for POST/PATCH
Error Format	Consistent JSON structure with error codes
Versioning	URL path preferred (/v1/users)
Documentation	OpenAPI 3.1

Related Resources

Resource	Description
Microsoft REST API Guidelines	Comprehensive API design guide
Google API Design Guide	Resource-oriented design principles
JSON:API Specification	Standard for JSON response format
OpenAPI Specification	API documentation standard

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.

Questions?

Open an issue on GitHub.