skillmd.
Methodologydesign

rest-api-design

Methodology skill.md.

aj-geddes/useful-ai-prompts
View source

Install

npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill rest-api-design

Use with your agent

ClaudeCursorOpenAIGemini

Install the rest-api-design skill, then use it as build context. Run: npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill rest-api-design. Then read the installed skill.md and follow its guidance to build or refactor my project.

REST API Design

Table of Contents

Overview

Design REST APIs that are intuitive, consistent, and follow industry best practices for resource-oriented architecture.

When to Use

  • Designing new RESTful APIs
  • Creating endpoint structures
  • Defining request/response formats
  • Implementing API versioning
  • Documenting API specifications
  • Refactoring existing APIs

Quick Start

Minimal working example:

✅ Good Resource Names (Nouns, Plural)
GET    /api/users
GET    /api/users/123
GET    /api/users/123/orders
POST   /api/products
DELETE /api/products/456

❌ Bad Resource Names (Verbs, Inconsistent)
GET    /api/getUsers
POST   /api/createProduct
GET    /api/user/123  (inconsistent singular/plural)

Reference Guides

Detailed implementations in the references/ directory:

GuideContents
Resource NamingResource Naming, HTTP Methods & Operations
Request ExamplesRequest Examples
Query ParametersQuery Parameters
Response FormatsResponse Formats
HTTP Status CodesHTTP Status Codes, API Versioning, Authentication & Security, Rate Limiting Headers
OpenAPI DocumentationOpenAPI Documentation
Complete Example: Express.jsconst express = require("express");

Best Practices

✅ DO

  • Use nouns for resources, not verbs
  • Use plural names for collections
  • Be consistent with naming conventions
  • Return appropriate HTTP status codes
  • Include pagination for collections
  • Provide filtering and sorting options
  • Version your API
  • Document thoroughly with OpenAPI
  • Use HTTPS
  • Implement rate limiting
  • Provide clear error messages
  • Use ISO 8601 for dates

❌ DON'T

  • Use verbs in endpoint names
  • Return 200 for errors
  • Expose internal IDs unnecessarily
  • Over-nest resources (max 2 levels)
  • Use inconsistent naming
  • Forget authentication
  • Return sensitive data
  • Break backward compatibility without versioning