skills.rest
Long-NguyenHai
Long-NguyenHaiCOMMUNITY
Explore all skills by this author →
GitHub

api-design

Design RESTful APIs with resource naming, status codes, pagination, and versioning.

Updated Jul 4, 2026
Search Tags:#best practices#API design#REST API#API documentation#HTTP#RESTful
One-click install
npx skills add https://github.com/Long-NguyenHai/warehouse-ai --skill api-design-long-nguyenhai
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/Long-NguyenHai/warehouse-ai/tree/main/.agents/skills/api-design
Command: npx skills add https://github.com/Long-NguyenHai/warehouse-ai --skill api-design-long-nguyenhai

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill provides guidelines for designing RESTful APIs, addressing common pitfalls and helping you create APIs that are developer-friendly and easy to maintain.

Core Features & Use Cases

  • Best Practices: Offers a comprehensive guide to REST API design, including naming conventions, status codes, and pagination patterns.
  • Resource Design: Provides detailed instructions for URL structure, naming rules, and resource relationships.
  • HTTP Methods and Status Codes: Explains the semantics of HTTP methods and common status codes, helping developers understand their usage.
  • Response Format: Details best practices for structuring API responses, including success, error, and collection responses.
  • Pagination: Discusses both offset-based and cursor-based pagination, providing guidelines for when to use each.
  • Filtering, Sorting, and Search: Offers techniques for implementing filtering, sorting, and full-text search capabilities in APIs.
  • Authentication and Authorization: Explains various authentication methods and authorization patterns to ensure secure API access.
  • Rate Limiting: Details how to implement rate limiting to prevent abuse and ensure API stability.
  • Versioning: Discusses different versioning strategies and best practices to maintain backward compatibility.
  • Implementation Patterns: Provides examples of API implementation using different programming languages and frameworks.
  • API Design Checklist: Offers a checklist to ensure that your API design meets best practices before deployment.

Quick Start

Review the API design guidelines for your new API project to ensure it follows best practices and is developer-friendly.

Frequently Asked Questions about api-design

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

FAQPage Schema
What are the best practices for REST API resource naming and URL structure?▼

REST API best practices for resource naming involve using plural nouns, logical hierarchical URL structures, and clear naming rules to define resource relationships. This ensures your API is developer-friendly, scalable, and easy to maintain.

How do I choose the right HTTP status codes and methods for my RESTful API?▼

Choosing the right HTTP status codes and methods requires understanding their semantics. Use standard HTTP methods for actions and appropriate status codes for success, redirection, client errors, and server errors to communicate outcomes clearly.

When should I use cursor-based pagination versus offset-based pagination in an API?▼

Use cursor-based pagination for large datasets where data changes frequently, as it prevents skipping items. Offset-based pagination is simpler and suitable for smaller, static collections where sequential page access is needed.

How do I implement filtering, sorting, and searching in a REST API?▼

Implement filtering, sorting, and searching in a REST API by using query parameters to pass criteria. This allows clients to request specific subsets of data, order results by attributes, and perform full-text searches efficiently.

What is the best way to handle REST API versioning to maintain backward compatibility?▼

The best way to handle REST API versioning involves adopting a consistent versioning strategy, such as URI path or header versioning. This maintains backward compatibility while allowing you to introduce new features safely.

How do I design secure REST API authentication and rate limiting?▼

Design secure REST API authentication by implementing methods like OAuth or API keys to control access. Apply rate limiting to prevent abuse, protect API stability, and ensure fair resource allocation among clients.

Related Skills

Explore More Software Engineering Skills→
suhwansuhwan

phase-1-schema

Define project terminology and data structures with schema documentation output.

Community
Intermediate
OneWave-AIOneWave-AI
245

api-documentation-writer

Generate OpenAPI/Swagger specs and endpoint documentation for REST, GraphQL, WebSocket, and gRPC APIs.

Official
Basic
cenjiecenjie

api-security-hardening

Secure REST APIs with authentication, rate limiting, CORS, and input validation.

Community
Advanced
majiayu000majiayu000
258

api-design

Design API contracts for REST, GraphQL, and gRPC contexts.

Community
Advanced