360 Secure SkillHub
360 安全技能中心

rest-api-design

面向 REST API 设计的参考型 Skill，提供资源命名、请求与查询参数、响应格式、HTTP 状态码、版本化、认证安全、限流头和 OpenAPI 文档等指南，并含 Express.js 示例、API 脚手架模板与校验脚本，适合新建或重构 API 时查阅。

aj-geddes
热度 0.00
最近更新 2026-10-19 07:39:13
分类：开发依赖：读写文件 / 代码执行应用场景：API 集成 / 模板 / 概念解释

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add aj-geddes/useful-ai-prompts/rest-api-design
Metadata
name
rest-api-design
description
Design RESTful APIs following best practices for resource modeling, HTTP methods, status codes, versioning, and documentation. Use when creating new APIs, designing endpoints, or improving existing API architecture.

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:

Guide Contents
Resource Naming Resource Naming, HTTP Methods & Operations
Request Examples Request Examples
Query Parameters Query Parameters
Response Formats Response Formats
HTTP Status Codes HTTP Status Codes, API Versioning, Authentication & Security, Rate Limiting Headers
OpenAPI Documentation OpenAPI Documentation
Complete Example: Express.js const 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