skills.rest
Yash-Awasthi
Yash-AwasthiCOMMUNITY
Explore all skills by this author →
GitHub

rest-api-design

Designs RESTful APIs with resource naming, HTTP methods, status codes, and response formats.

Updated Aug 28, 2026
Search Tags:#api design#backend#rest api#pagination#status codes#http methods#resource naming
One-click install
npx skills add https://github.com/Yash-Awasthi/adapfit --skill rest-api-design-yash-awasthi
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: rest-api-design
Source: https://github.com/Yash-Awasthi/adapfit/tree/main/.agents/skills/rest-api-design
Command: npx skills add https://github.com/Yash-Awasthi/adapfit --skill rest-api-design-yash-awasthi

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Inconsistent API design leads to confusing endpoints, wrong status codes, and poor developer experience. This Skill provides clear conventions for building RESTful APIs that are predictable and easy to consume. ## Core Features & Use Cases - Resource Naming Conventions: Enforces noun-based, plural, hierarchical URL structures instead of verb-based endpoints. - HTTP Method & Status Code Guidance: Maps CRUD operations to correct methods (GET, POST, PUT, PATCH, DELETE) and status codes (200, 201, 204, 400, 401, 403, 404, 429). - Standardized Response Formats: Provides JSON envelope patterns for single resources, collections with pagination, and query parameters for filtering, sorting, and field selection. - Use Case: When scaffolding a new FastAPI or Express backend, use this Skill to define consistent endpoint structures, pagination links, and error responses before writing any route handlers. ## Quick Start Design a RESTful API for a products resource with proper naming, pagination, and status codes.

Frequently Asked Questions about rest-api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design a RESTful API with proper conventions?▼

Use plural nouns for resources (e.g., /api/users), map CRUD operations to HTTP methods, and return appropriate status codes like 201 for creation and 204 for deletion. Version your API via the URL path such as /api/v1/.

What HTTP status codes should a REST API return?▼

Return 200 for successful reads and updates, 201 for resource creation, 204 for successful deletion, 400 for validation errors, 401 for missing auth, 403 for insufficient permissions, 404 for missing resources, and 429 for rate limiting.

Should REST API URLs use verbs or nouns?▼

REST URLs should use nouns, not verbs. Use /api/users/123 instead of /api/getUser, and let the HTTP method express the action. Hierarchical paths like /api/users/123/orders express relationships between resources.

How do I add pagination to a REST API collection endpoint?▼

Accept page and limit query parameters, then return a pagination object with page, limit, total, and totalPages alongside the data array. Include HATEOAS-style links for self and next pages to help clients navigate results.

When should I use PATCH versus PUT for updates?▼

Use PATCH for partial updates that modify only specified fields, and PUT when replacing the entire resource representation. Both are idempotent, but PUT requires the client to send the complete resource state.

Related Skills

Explore More Software Engineering Skills→
anorthamanortham
2

brainstorming

Gather project context, align stakeholders, and define success criteria before coding.

Community
Advanced
igpastorigpastor

API Design Skill

Generate framework-specific API endpoints with routes, controllers, and OpenAPI documentation.

Community
Intermediate
vishalsachdevvishalsachdev
2

secure-nextjs-api-routes

Secure Next.js 13+ App Router API routes with composable middleware.

Community
Advanced
elmochilyaselmochilyas
8

laravel-api-grpc

Implement gRPC in Laravel 13 microservices using Protocol Buffers and RoadRunner.

Community
Advanced