api-design

What this skill does

When applied, it prepends a system prompt before your request is sent — no extra calls and no change to how you are billed beyond the added tokens.

---
name: api-design
description: REST API tasarım kalıpları; kaynak isimlendirme, durum kodları, sayfalama, filtreleme, hata yanıtları, versiyonlama ve üretim API'leri için hız sınırlama içerir.
origin: ECC
---

# API Tasarım Kalıpları

Tutarlı, geliştirici dostu REST API'leri tasarlamak için konvansiyonlar ve en iyi uygulamalar.

## Ne Zaman Aktifleştirmeli

- Yeni API endpoint'leri tasarlarken
- Mevcut API sözleşmelerini incelerken
- Sayfalama, filtreleme veya sıralama eklerken
- API'ler için hata işleme uygularken
- API versiyonlama stratejisi planlarken
- Halka açık veya iş ortağı odaklı API'ler oluştururken

## Kaynak Tasarımı

### URL Yapısı

```
# Kaynaklar isim, çoğul, küçük harf, kebab-case
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# İlişkiler için alt kaynaklar
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/orders

# CRUD'a uymayan aksiyonlar (fiilleri dikkatli kullanın)
POST   /api/v1/orders/:id/cancel
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh
```

### İsimlendirme Kuralları

```
# İYİ
/api/v1/team-members          # çok sözcüklü kaynaklar için kebab-case
/api/v1/orders?status=active  # filtreleme için query parametreleri
/api/v1/users/123/orders      # sahiplik için iç içe kaynaklar

# KÖTÜ
/api/v1/getUsers              # URL'de fiil
/api/v1/user                  # tekil (çoğul kullanın)
/api/v1/team_members          # URL'lerde snake_case
/api/v1/users/123/getOrders   # iç içe kaynaklarda fiil
```

## HTTP Metodları ve Durum Kodları

### Metod Semantiği

| Metod | Idempotent | Güvenli | Kullanım Amacı |
|--------|-----------|------|---------|
| GET | Evet | Evet | Kaynakları getir |
| POST | Hayır | Hayır | Kaynak oluştur, aksiyonları tetikle |
| PUT | Evet | Hayır | Kaynağın tam değişimi |
| PATCH | Hayır* | Hayır | Kaynağın kısmi güncellemesi |
| DELETE | Evet | Hayır | Kaynağı kaldır |

*PATCH uygun implementasyonla idempotent y

Use this skill

{
  "model": "gpt-4o-mini",
  "skill": "imp-76569209-7a33-48e2-9ca9-a94914967ce3",
  "messages": [{ "role": "user", "content": "…" }]
}

More skills