api-design
Guide for designing and documenting RESTful APIs. Use when asked to design an API, create endpoints, or document an API.
Informations de source
- Dépôt
- microsoft/haste
- Dernière activité de la source
- 17 juin 2026 à 22:19
- Langue détectée de SKILL.md
- anglais
- Étoiles
- 109
- Forks
- 19
Options d'installation
Le prompt qui vérifie d'abord la source est sélectionné par défaut. Vous pouvez passer à une commande directe ou télécharger une copie locale.
Vérifiez les fichiers source
Lisez SKILL.md et les fichiers associés affichés par SkillsMP avant de décider de l'installer.
Affichage de SKILL.md
SKILL.md
Instructions source · Aperçu en lecture seule- name
- api-design
- description
- Guide for designing and documenting RESTful APIs. Use when asked to design an API, create endpoints, or document an API.
- source
- Internal engineering practices, REST API conventions
- domain
- architecture
- level
- intermediate
- agents
- ["backend-dev","gis"]
- created_date
- 2026-04-27
- last_validated
- validated_by
- status
- draft
# API Design
## Overview
Standards and patterns for designing consistent, well-documented RESTful APIs. Covers naming, HTTP methods, error handling, status codes, and documentation requirements.
## Key Concepts
### Naming Conventions
- Plural nouns for resources: `/users`, `/orders`, `/products`
- Kebab-case for multi-word: `/user-profiles`
- Nest related resources: `/users/{id}/orders`
- Query params for filtering: `/users?role=admin&active=true`
### HTTP Methods
| Method | Purpose | Idempotent | Response |
|--------|---------|------------|----------|
| GET | Read | Yes | 200 + body |
| POST | Create | No | 201 + body + Location |
| PUT | Replace | Yes | 200 + body |
| PATCH | Partial update | No | 200 + body |
| DELETE | Remove | Yes | 204 (no body) |
### Error Response Format
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable description",
"details": [
{"field": "email", "message": "Invalid email format"}
]
}
}
```
### Status Codes
- **200**: Success — **201**: Created — **204**: No content
- **400**: Bad request — **401**: Unauthorized — **403**: Forbidden
- **404**: Not found — **409**: Conflict — **422**: Unprocessable
- **429**: Rate limited — **500**: Internal error
## Decision Framework
| Scenario | Method | Path | Status |
|----------|--------|------|--------|
| List items | GET | /items | 200 |
| Get one item | GET | /items/{id} | 200 / 404 |
| Create item | POST | /items | 201 |
| Full update | PUT | /items/{id} | 200 / 404 |
| Partial update | PATCH | /items/{id} | 200 / 404 |
| Delete item | DELETE | /items/{id} | 204 / 404 |
| Search | GET | /items?q=term | 200 |
| Bulk action | POST | /items/batch | 200 / 207 |
## Documentation Requirements
Every endpoint must document:
1. HTTP method and path
2. Description
3. Request parameters (path, query, body) with types
4. Response schema with examples
5. Error codes and descriptions
6. Authentication requirements
## Common Pitfalls
- **Using verbs in URLs** — Use nouns: `/users` not `/getUsers`
- **Inconsistent error format** — Use the same error schema everywhere
- **Missing pagination** — Any list endpoint that can grow needs pagination
- **No versioning strategy** — Decide early: URL (`/v1/`) or header-based
Voir sur GitHub