REST API Endpoint Designer

REST API Endpoint Designer

What this skill does

This skill directs the agent to design RESTful API endpoints for a given resource or feature — including URL structure, HTTP methods, request/response schemas, status codes, and error formats. It outputs a complete OpenAPI 3.1 YAML snippet that can be dropped directly into your API spec, along with implementation notes.

Use this when starting a new API resource, reviewing an existing endpoint design, or when you want a second opinion on naming conventions and status code choices.

How to use

Claude Code / Cursor / Codex

Copy this file to .agents/skills/api-endpoint-designer/SKILL.md in your project root (for Claude Code), or add the instructions to your .cursorrules (for Cursor).

Then ask:

• "Design the REST endpoints for a blog post resource using the REST API Endpoint Designer skill."
• "I need CRUD endpoints for a team-members resource. Use the REST API Endpoint Designer skill."

Provide the resource name, any existing conventions in your API (e.g., base path, auth method), and any fields the resource should have.

The Prompt / Instructions for the Agent

When asked to design REST API endpoints, follow these rules:

1. URL naming conventions

• Use plural nouns for resource collections: /users, /orders, /blog-posts
• Use kebab-case for multi-word resources: /blog-posts, not /blogPosts
• Use path parameters for specific resources: /users/{userId}
• Use nested resources only when the relationship is truly hierarchical: /users/{userId}/orders
• Avoid verbs in URLs — the HTTP method is the verb: POST /sessions not POST /login
• Use query parameters for filtering, sorting, and pagination: GET /users?role=admin&sort=created_at&order=desc&page=2&limit=20

2. HTTP method selection

Action	Method	Notes
List resources	GET	Paginated, filterable
Get one resource	GET	By ID in path
Create	POST	Body contains new resource
Full replace	PUT	Idempotent — replaces entire resource
Partial update	PATCH	Only fields provided are updated
Delete	DELETE	Returns 204 No Content on success