REST API tasarımınızı otomatik linting, breaking-change tespiti ve tasarım skorkaritleri ile kapsamlı şekilde gözden geçirin. Tutarsız kurallar, eksik versiyonlama ve tasarım sorunlarını API'lar yayına çıkmadan yakalar. PR'larda endpoint eklemesi/değişikliğini incelerken, mevcut API'nizi v2 migrasyonu için denetlerken veya ekibiniz için API standartları belirlerken kullanın.
cd ~/.claude/skills
git clone https://github.com/alirezarezvani/claude-skills.git claude-skillsmkdir -p ~/.claude/skills/api-design-reviewer
curl -fsSL https://raw.githubusercontent.com/alirezarezvani/claude-skills/HEAD/.gemini/skills/api-design-reviewer/SKILL.md \
-o ~/.claude/skills/api-design-reviewer/SKILL.mdTier: POWERFUL
Kategori: Mühendislik / Mimari
Bakım Sorumlusu: Claude Skills Team
API Tasarım İncelemeci becerisi, API tasarımlarının kapsamlı analiz ve incelemesini sağlar; REST kurallarına, en iyi uygulamalara ve endüstri standartlarına odaklanır. Bu beceri, mühendislik ekiplerine otomatik linting, breaking change tespiti ve tasarım skorkarti aracılığıyla tutarlı, bakım yapılabilir ve iyi tasarlanmış API'ler oluşturmalarına yardımcı olur.
✅ İyi Örnekler:
- /api/v1/users
- /api/v1/user-profiles
- /api/v1/orders/123/line-items
❌ Kötü Örnekler:
- /api/v1/getUsers
- /api/v1/user_profiles
- /api/v1/orders/123/lineItems
Collection Resources: /api/v1/users
Individual Resources: /api/v1/users/123
Nested Resources: /api/v1/users/123/orders
Actions: /api/v1/users/123/activate (POST)
Filtering: /api/v1/users?status=active&role=admin
/api/v1/users
/api/v2/users
Avantajları: Net, açık, yönlendirmesi kolay
Dezavantajları: URL çoğalması, caching karmaşıklığı
GET /api/users
Accept: application/vnd.api+json;version=1
Avantajları: Temiz URL'ler, content negotiation
Dezavantajları: Daha az görünür, manuel test zor
GET /api/users
Accept: application/vnd.myapi.v1+json
Avantajları: RESTful, multiple representations'ı destekler
Dezavantajları: Karmaşık, uygulanması zor
/api/users?version=1
Avantajları: Uygulanması basit
Dezavantajları: RESTful değil, yoksayılabilir
{
"data": [...],
"pagination": {
"offset": 20,
"limit": 10,
"total": 150,
"hasMore": true
}
}
{
"data": [...],
"pagination": {
"nextCursor": "eyJpZCI6MTIzfQ==",
"hasMore": true
}
}
{
"data": [...],
"pagination": {
"page": 3,
"pageSize": 10,
"totalPages": 15,
"totalItems": 150
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The request contains invalid parameters",
"details": [
{
"field": "email",
"code": "INVALID_FORMAT",
"message": "Email address is not valid"
}
],
"requestId": "req-123456",
"timestamp": "2024-02-16T13:00:00Z"
}
}
Authorization: Bearer <token>
X-API-Key: <api-key>
Authorization: Api-Key <api-key>
Authorization: Bearer <oauth-access-token>
{
"user": {
"id": "123",
"roles": ["admin", "editor"],
"permissions": ["read:users", "write:orders"]
}
}
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"retryAfter": 3600
}
}
{
"id": "123",
"name": "John Doe",
"email": "john@example.com",
"_links": {
"self": { "href": "/api/v1/users/123" },
"orders": { "href": "/api/v1/users/123/orders" },
"profile": { "href": "/api/v1/users/123/profile" },
"deactivate": {
"href": "/api/v1/users/123/deactivate",
"method": "POST"
}
}
}
POST /api/v1/payments
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Cache-Control: public, max-age=3600
ETag: "123456789"
Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT
?fields=id,name,email)API specification'larını REST convention'ları ve en iyi uygulamalar açısından analiz eder.
Özellikler:
API specification versiyonlarını karşılaştırarak breaking change'leri tanımlar.
Özellikler:
API tasarım kalitesinin kapsamlı puanlamasını sağlar.
Özellikler:
- name: "api-linting"
run: python scripts/api_linter.py openapi.json
- name: "breaking-change-detection"
run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json
- name: "api-scorecard"
run: python scripts/api_scorecard.py openapi.json
#!/bin/bash
python engineering/api-design-reviewer/scripts/api_linter.py api/openapi.json
if [ $? -ne 0 ]; then
echo "API linting failed. Please fix the issues before committing."
exit 1
fi
API Tasarım İncelemeci becerisi, yüksek kaliteli REST API'ler inşa etmek, incelemek ve bakım yapmak için kapsamlı bir framework sağlar. Bu yönergeleri takip ederek ve sağlanan tool'ları kullanarak, geliştirme ekipleri tutarlı, iyi dokümante edilmiş, güvenli ve bakım yapılabilir API'ler oluşturabilir.
Linting, breaking change detection ve scoring tool'larının düzenli kullanımı, sürekli improvement'ı sağlar ve geliştirme lifecycle'ı boyunca API kalitesinin korunmasına yardımcı olur.
Herhangi bir yaratıcı çalışmaya başlamadan önce bunu mutlaka kullanın - feature oluştururken, component inşa ederken, functionality eklerken veya davranış değiştirirken. Kullanıcı niyetini, gereksinimleri ve tasarımı implementation öncesinde araştırır.
Uygulama tamamlandığında, tüm testler geçtiğinde ve çalışmanızı nasıl entegre edeceğinize karar vermeniz gerektiğinde kullanın - merge, PR veya cleanup seçeneklerini sunarak geliştirme sürecinin tamamlanmasını rehberlik eder.
Kod incelemesi geri bildirimi alırken, önerileri uygulamadan önce kullanın; özellikle geri bildirim belirsiz veya teknik olarak şüpheli görünüyorsa - performatif anlaşmadan veya körü körüne uygulamadan ziyade teknik titizlik ve doğrulama gerekir.
Görevleri tamamlarken, büyük özellikleri hayata geçirirken veya merge etmeden önce çalışmanın gereksinimleri karşıladığını doğrulamak için kullanın.
Yeni bir feature üzerinde çalışmaya başlarken veya implementasyon planını yürütmeden önce kullanın - native araçlar veya git worktree fallback aracılığıyla izole edilmiş bir workspace sağlar.
Herhangi bir konuşma başlatırken kullanın - skill'lerin nasıl bulunacağını ve kullanılacağını belirler, clarification soruları da dahil olmak üzere HERHANGİ bir yanıt vermeden önce skill invocation gerektirir.