http-best-practices
HTTPプロトコルの仕様に基づき、RESTful APIおよびWebサービス実装における通信設計を提供。ステータスコード、ヘッダー、キャッシュ、冪等性設計を網羅。Anchors:• HTTP/2 in Action (Barry Pollard) / 適用: プロトコル仕様・パフォーマンス / 目的: 効率的なHTTP通信• RESTful Web Services (Richardson, Ruby) / 適用: REST設計原則 / 目的: 一貫したAPI設計• Web API Design (Brian Mulloy) / 適用: 実践的なAPI設計パターン / 目的: 使いやすいAPITrigger:Use when designing REST APIs, implementing HTTP clients, configuring cache strategies, setting security headers, or ensuring idempotency.http, rest api, status codes, cache-control, cors, idempotency, headers, http/2, keep-alive
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for designing and implementing high-quality RESTful APIs based on industry-standard HTTP protocols. It covers critical aspects such as status code selection, security header configuration, caching strategies, and idempotency design to ensure consistent, secure, and efficient web service communication. By integrating expert references and automated validation scripts, it helps developers build scalable and professional-grade web APIs.
Use Cases
- Designing a new RESTful API from scratch with standardized status codes and consistent response formats.
- Optimizing web service performance using HTTP/2 features, connection pooling, and advanced caching strategies like ETag and Cache-Control.
- Securing API endpoints by implementing and validating essential security headers such as CORS, CSP, and HSTS.
- Ensuring data integrity in distributed systems by designing robust idempotency mechanisms for non-idempotent HTTP methods.
- Auditing existing API implementations to identify and fix deviations from HTTP best practices using automated verification scripts.
| name | http-best-practices |
|---|---|
| description | | |
| • HTTP/2 in Action (Barry Pollard) / 適用 | プロトコル仕様・パフォーマンス / 目的: 効率的なHTTP通信 |
| • RESTful Web Services (Richardson, Ruby) / 適用 | REST設計原則 / 目的: 一貫したAPI設計 |
| • Web API Design (Brian Mulloy) / 適用 | 実践的なAPI設計パターン / 目的: 使いやすいAPI |
HTTP Best Practices
概要
HTTPプロトコルの仕様に基づき、RESTful APIおよびWebサービス実装における正しく効率的な通信設計を提供。 ステータスコード選択、ヘッダー管理、キャッシュ戦略、コネクション最適化、セキュリティヘッダー設定、冪等性設計を網羅。
ワークフロー
Phase 1: 要件分析
目的: API設計のための通信仕様要件を明確化
アクション:
references/Level1_basics.mdでHTTPの基本概念を確認- API仕様に基づき適用すべきHTTPパターンを特定
- セキュリティ要件に基づき必要なヘッダーを洗い出す
Task: agents/requirements-analysis.md を参照
Phase 2: 詳細設計
目的: HTTPプロトコル仕様に基づいた詳細設計を実施
アクション:
references/status-codes.mdでステータスコード選択基準を確認references/headers-best-practices.mdでヘッダー設計references/caching-strategies.mdでキャッシュ戦略設計references/idempotency.mdで冪等性実装パターンを確認
Task: agents/detailed-design.md を参照
Phase 3: 実装検証
目的: 設計の実装可能性を検証し記録
アクション:
scripts/analyze-headers.mjsでセキュリティヘッダー検証scripts/validate-http-client.mjsでHTTPクライアント検証scripts/log_usage.mjsで実行記録を保存
Task: agents/implementation-verification.md を参照
Task仕様ナビ
| Task | 起動タイミング | 入力 | 出力 |
|---|---|---|---|
| requirements-analysis | Phase 1開始時 | API仕様 | 要件定義書 |
| detailed-design | Phase 2開始時 | 要件定義書 | 設計書 |
| implementation-verification | Phase 3開始時 | 設計書 | 検証レポート |
詳細仕様: 各Taskの詳細は agents/ ディレクトリの対応ファイルを参照
ベストプラクティス
すべきこと
- 各エンドポイントに標準ステータスコードを明示的に定義
- CORS、CSP、HSTSなどセキュリティヘッダーを一元設定
- Cache-Control、ETagをリソース種別ごとに定義
- PUT/DELETE/PATCHはIdempotency-Keyで冪等性を確保
- Keep-Alive、HTTP/2、コネクションプーリングを活用
- エラーレスポンス形式を統一
避けるべきこと
- 401/403の意味を誤って使用
- セキュリティヘッダーなしでAPI公開
- キャッシュ無効化戦略なしでキャッシュ有効化
- 冪等性保証なしで外部API連携
- リクエストごとにTCP接続を確立
リソース参照
references/(詳細知識)
| リソース | パス | 内容 |
|---|---|---|
| 基礎知識 | See references/Level1_basics.md | HTTP基本概念 |
| 中級知識 | See references/Level2_intermediate.md | 実装パターン |
| 上級知識 | See references/Level3_advanced.md | HTTP/2最適化 |
| 専門家向け | See references/Level4_expert.md | 高負荷環境設計 |
| ステータスコード | See references/status-codes.md | 2xx/3xx/4xx/5xx選択 |
| ヘッダー設計 | See references/headers-best-practices.md | セキュリティヘッダー |
| コネクション管理 | See references/connection-management.md | Keep-Alive/HTTP/2 |
| 冪等性設計 | See references/idempotency.md | Idempotency-Key実装 |
scripts/(決定論的処理)
| スクリプト | 用途 | 使用例 |
|---|---|---|
validate-http-client.mjs |
HTTPクライアント検証 | node scripts/validate-http-client.mjs src/api.ts |
analyze-headers.mjs |
ヘッダー分析 | node scripts/analyze-headers.mjs response.json |
log_usage.mjs |
フィードバック記録 | node scripts/log_usage.mjs --result success |
assets/(テンプレート)
| テンプレート | 用途 |
|---|---|
http-client-template.ts |
HTTPクライアント実装 |
api-response-template.json |
APIレスポンス設計 |
変更履歴
| Version | Date | Changes |
|---|---|---|
| 2.0.0 | 2026-01-02 | 18-skills.md完全準拠、description簡潔化 |
| 1.1.0 | 2025-12-31 | Phase詳細化、Task仕様ナビ追加 |
| 1.0.0 | 2025-12-24 | 初版 |