api-design

Provide RESTful API design guidelines covering naming, status codes, pagination, and versioning.

Updated Jun 22, 2026
One-click install
npx skills add https://github.com/hector-manny/bussbot --skill api-design-hector-manny
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/hector-manny/bussbot/tree/main/.cursor/.agents/skills/api-design
Command: npx skills add https://github.com/hector-manny/bussbot --skill api-design-hector-manny

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill unit addresses the complexities of designing and implementing production-grade REST APIs, providing a comprehensive guide and patterns to follow.

Core Features & Use Cases

  • API Design Patterns: Offers best practices for naming, status codes, pagination, filtering, error responses, versioning, and rate limiting.
  • Resource Design: Detailed guidance on URL structure, naming rules, and handling relationships and actions.
  • HTTP Methods and Status Codes: Comprehensive reference for understanding method semantics and status code usage.
  • Response Format: Templates for success, collection, and error responses, including JSON examples.
  • Pagination: Covers both offset-based and cursor-based pagination with use cases.
  • Filtering, Sorting, and Search: Strategies for implementing filtering, sorting, and search functionalities.
  • Authentication and Authorization: Discusses token-based auth and authorization patterns.
  • Rate Limiting: Details on implementing rate limiting with headers and tiers.
  • Versioning: Strategies for URL and header versioning with a versioning strategy guide.
  • Implementation Patterns: Code snippets for TypeScript (Next.js), Python (Django), and Go demonstrating implementation patterns.
  • API Design Checklist: A checklist for ensuring the quality of API design.

Quick Start

To get started with designing an API, run the skill unit 'api-design' and follow the provided guide for REST API design patterns and best practices.

Frequently Asked Questions about 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 naming and URL structure?

Designing a RESTful API requires following resource design guidelines for URL structure, naming rules, and handling relationships. This skill provides detailed patterns and best practices for structuring resources, actions, and endpoints to ensure production-grade API consistency.

What are the best practices for API pagination, filtering, and sorting?

Best practices for API pagination, filtering, and sorting include using both offset-based and cursor-based pagination strategies. This skill provides implementation patterns for filtering, sorting, and search functionalities to handle large datasets efficiently in REST APIs.

How do I implement API versioning and rate limiting in a REST API?

Implementing API versioning and rate limiting involves choosing URL or header versioning strategies and applying rate limit headers and tiers. This skill details strategies for versioning and rate limiting to maintain stable and secure REST API operations.

Does this API design skill provide implementation examples for Python, TypeScript, and Go?

Yes, this skill provides code snippets and implementation patterns for TypeScript (Next.js), Python (Django), and Go. These examples demonstrate how to apply REST API design patterns, response formats, and authentication methods directly in those frameworks.

What HTTP status codes and error response formats should my REST API use?

Your REST API should use standard HTTP status codes based on method semantics and structured JSON templates for error responses. This skill offers a comprehensive reference for status code usage and response formatting for success, collection, and error states.

When should I use cursor-based pagination instead of offset-based pagination in my REST API?

Cursor-based pagination is preferred for large, real-time datasets where data changes frequently, while offset-based pagination suits static datasets. This skill covers both pagination strategies with specific use cases to guide your REST API implementation choices.