Rest Api Design

by secondsky88378361314fMIT227 starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 10 days ago

Designs RESTful APIs with proper resource naming, HTTP methods, status codes, and response formats. Use when building new APIs, establishing API conventions, or designing developer-friendly interfaces.

Instructions onlySoftware Development

AI-generated overview

Guides RESTful API design with resource naming, HTTP methods, status codes, and response formats.

What it does: This skill provides conventions for designing RESTful APIs, covering resource naming with nouns and hierarchy, HTTP method semantics, and status code selection. It also specifies JSON response and collection formats, including pagination and links, plus query parameters for filtering, sorting, pagination, and field selection. It ends with a short list of best practices such as URL versioning and OpenAPI documentation.
When to use it: Use it when building a new API, establishing team-wide API conventions, or designing developer-friendly interfaces. It suits early design decisions about endpoints, payloads, and error responses rather than runtime implementation.
Requirements: No tools, packages, runtimes, credentials, or network access are required; it is instructions only and ships no scripts.

REST API Design

Design RESTful APIs with proper conventions and developer experience.

Resource Naming

# Good - nouns, plural, hierarchicalGET    /api/usersGET    /api/users/123GET    /api/users/123/ordersPOST   /api/usersPATCH  /api/users/123DELETE /api/users/123
# Bad - verbs, actions in URLGET    /api/getUsersPOST   /api/createUserPOST   /api/users/123/delete

# Good - nouns, plural, hierarchicalGET    /api/usersGET    /api/users/123GET    /api/users/123/ordersPOST   /api/usersPATCH  /api/users/123DELETE /api/users/123
# Bad - verbs, actions in URLGET    /api/getUsersPOST   /api/createUserPOST   /api/users/123/delete

HTTP Methods

Status Codes

Code	Meaning	Use For
200	OK	Successful GET, PATCH
201	Created	Successful POST
204	No Content	Successful DELETE
400	Bad Request	Validation errors
401	Unauthorized	Missing auth
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limited

Response Format

json

{  "data": {    "id": "123",    "type": "user",    "attributes": {      "name": "John",      "email": "[email protected]"    }  },  "meta": {    "requestId": "req_abc123"  }}

{  "data": {    "id": "123",    "type": "user",    "attributes": {      "name": "John",      "email": "[email protected]"    }  },  "meta": {    "requestId": "req_abc123"  }}

Collection Response

json

{  "data": [...],  "pagination": {    "page": 1,    "limit": 20,    "total": 150,    "totalPages": 8  },  "links": {    "self": "/api/users?page=1",    "next": "/api/users?page=2"  }}

{  "data": [...],  "pagination": {    "page": 1,    "limit": 20,    "total": 150,    "totalPages": 8  },  "links": {    "self": "/api/users?page=1",    "next": "/api/users?page=2"  }}

Query Parameters

GET /api/products?category=electronics    # FilteringGET /api/products?sort=-price,name        # SortingGET /api/products?page=2&limit=20         # PaginationGET /api/products?fields=id,name,price    # Field selection

GET /api/products?category=electronics    # FilteringGET /api/products?sort=-price,name        # SortingGET /api/products?page=2&limit=20         # PaginationGET /api/products?fields=id,name,price    # Field selection

Best Practices

Use nouns for resources, not verbs
Version API via URL path (/api/v1/)
Return appropriate status codes
Include pagination for collections
Document with OpenAPI/Swagger

Source and attribution

Source:secondsky/claude-skillsinplugins/rest-api-design/skills/rest-api-designat commit8837836

License: MIT

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Method	Purpose	Idempotent
GET	Read resource	Yes
POST	Create resource	No
PUT	Replace resource	Yes
PATCH	Partial update	Yes
DELETE	Remove resource	Yes

Rest Api Design

REST API Design

Resource Naming

HTTP Methods

Status Codes

Response Format

Collection Response

Query Parameters

Best Practices

Source and attribution

More from secondsky/claude-skills

Vulnerability Scanning

Web Performance Optimization

Web Performance Audit

Threejs

Tailwind V4 Shadcn

Technical Specification

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices