skills.rest
nguyenthienthanh
nguyenthienthanhCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-designer

Enforce consistent RESTful API design with versioning and OpenAPI documentation.

24|3|Updated Nov 25, 2025
Search Tags:#architecture#versioning#error handling#API design#OpenAPI#backend development#RESTful#pagination
One-click install
npx skills add https://github.com/nguyenthienthanh/aura-frog --skill api-designer-nguyenthienthanh
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-designer
Source: https://github.com/nguyenthienthanh/aura-frog/tree/main/aura-frog/skills/api-designer
Command: npx skills add https://github.com/nguyenthienthanh/aura-frog --skill api-designer-nguyenthienthanh

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Inconsistent API design leads to developer confusion, integration challenges, and maintenance headaches. This Skill provides expert guidance to design consistent, scalable RESTful APIs with proper versioning, documentation, and error handling, ensuring a robust and developer-friendly interface.

Core Features & Use Cases

  • RESTful Conventions: Guides on using appropriate HTTP methods, resource naming (plural nouns), and designing nested resources.
  • Versioning & Response Standards: Recommends URL path versioning and defines consistent success, list, and error response formats with proper HTTP status codes.
  • Pagination, Filtering & Sorting: Offers patterns for efficient data retrieval, including offset-based and cursor-based pagination, and standardized filtering/sorting mechanisms.
  • Use Case: When designing a new API for user management, use this skill to define RESTful endpoints like /v1/users, ensure proper status codes (201 for create, 200 for get), and include pagination for listing users, all documented with OpenAPI.

Quick Start

Design a RESTful API for managing products, including endpoints for listing, creating, retrieving, updating, and deleting products

Frequently Asked Questions about api-designer

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

FAQPage Schema
How do I design a RESTful API with consistent versioning and error handling?▼

RESTful API design uses URL path versioning (like /v1/users) combined with standardized error responses and proper HTTP status codes. This Skill guides you through establishing consistent response formats, status codes (201 for creation, 200 for success, 4xx/5xx for errors), and error structures across all endpoints to prevent integration confusion.

What's the best way to implement pagination and filtering in REST APIs?▼

Pagination and filtering use offset-based or cursor-based patterns to retrieve data efficiently. This Skill covers standardized query parameter conventions for pagination, filtering, and sorting across Node.js, Python, Go, and Laravel backends, ensuring clients can retrieve large datasets predictably.

How do I document my API to match OpenAPI standards?▼

OpenAPI documentation structures your API contract machine-readably. This Skill ensures your endpoints, request/response schemas, status codes, and error formats align with OpenAPI compliance, making your API automatically documentable and compatible with standard tools.

Can I enforce REST conventions across different backend frameworks?▼

Yes. This Skill applies REST conventions—proper HTTP methods, resource naming (plural nouns), nested resource design, and response standardization—consistently across Node.js, Python, Go, and Laravel stacks, so your API behaves predictably regardless of backend technology.

What resource naming patterns should I follow for nested endpoints?▼

Nested resources follow REST conventions using plural nouns and hierarchical paths (e.g., /v1/users/{userId}/orders). This Skill defines how to structure relationships between resources, design readable endpoints, and maintain consistency when modeling complex data hierarchies.

When should I use URL path versioning instead of other versioning strategies?▼

URL path versioning (/v1, /v2) makes API versions explicit in requests and simplifies routing. This Skill recommends URL path versioning as the standard approach for managing breaking changes and supporting multiple client versions simultaneously without ambiguity.

Related Skills

Explore More Software Engineering Skills→
veerababumanyamveerababumanyam

api-standards

Define RESTful API conventions for endpoints, responses, and pagination.

Community
Basic
mgd34msumgd34msu
4

openapi

Generate TypeScript types and client SDKs from OpenAPI 3.1 specifications.

Community
Advanced
camilooscargbaptistacamilooscargbaptista
7

api-documentation

Generate and review OpenAPI 3.1 specs for REST and GraphQL APIs.

Community
Intermediate
drewid74drewid74
8

service-integration

Design event-driven service integrations with webhooks, queues, and notifications.

Community
Advanced