rest-conventions_skill

Overview

This skill guides API designers to follow REST conventions when naming endpoints and choosing HTTP methods. It enforces using GET for reads, POST for creates, PUT/PATCH for updates, and DELETE for removals to preserve caching, tooling, and semantic correctness. Follow these rules to avoid broken HTTP behavior and hard-to-maintain APIs.

How this skill works

The skill reviews endpoint definitions and flags violations such as verbs in URLs or incorrect method use (e.g., POST for reads, GET for deletes). It recommends converting verbful routes into resource-based paths, moving filters to query parameters, and using action sub-resources for non-CRUD operations. It also provides patterns for pagination, sorting, and nested resources.

When to use it

• Designing any HTTP API endpoints or routes
• When someone suggests using POST to fetch data
• When unsure which HTTP method suits an operation
• Reviewing existing APIs for consistency and caching readiness
• Naming or refactoring endpoints to follow best practices

Best practices

• Use plural nouns for collections (e.g., /users, /orders) and resource IDs for single items (/users/:id).
• Use GET for safe reads; POST to create; PUT/PATCH for updates; DELETE to remove. Maintain idempotency expectations.
• Put filters, sorting, and pagination in query parameters (e.g., /orders?status=pending&page=2).
• Avoid verbs in URLs—use sub-resources or action endpoints for non-CRUD processes (e.g., POST /orders/:id/cancel).
• For very complex searches, provide a dedicated POST /search endpoint rather than using POST for ordinary reads. Document any legacy exceptions and migrate gradually.

Example use cases

• Converting POST /getOrders to GET /orders?userId=123 for caching and bookmarking
• Replacing POST /users/create with POST /users when creating new accounts
• Refactoring GET /deleteUser?id=123 into DELETE /users/123 to honor HTTP semantics
• Creating nested resource routes like GET /users/:id/orders and POST /users/:id/orders to model relationships
• Adding pagination: GET /products?page=2&limit=20 instead of embedding filters in request bodies