# İstek ve Yanıt Biçimi

https://dev.wisecp.com/tr/istek-ve-yanit-bicimi

Her adresin her ucunda tek bir zarf, tek bir durum kodu kümesi ve tek bir sayfalama biçimi.

## Genel Bakış

Bir çağrının biçimi kaynaktan kaynağa değişmez. Bir yanıtı okuyabiliyorsanız hepsini okuyabilirsiniz; bir kez yazılan hata yönetimi entegrasyonunuz büyüdükçe çalışmaya devam eder.

İşin çoğunu iki kural taşır. Başarılı yanıt içeriğini `data` altına koyar, başarısız olan ise makine tarafından okunabilir bir kodu `error` altına koyar. HTTP durumu her zaman hangisinin geldiğiyle uyuşur.

## Referans

### İstek

JSON'u `Content-Type: application/json` başlığıyla gönderin. Form kodlu POST da kabul edilir; istemci başlığı kuramıyorsa bu işe yarar. Süzgeç, sıralama ve sayfalama her metotta sorgu dizesinde taşınır.

- **Authorization: Bearer**: API anahtarı. Bunu kuramayan istemciler için yedek başlık `X-Api-Key`.
- **Content-Type**: Gövde JSON ise `application/json` verin. Vermezseniz gövde form alanı olarak okunur.
- **Idempotency-Key**: İsteğe bağlı, yalnız POST, 8 ile 191 karakter. Aynı anahtarın tekrarı, işi ikinci kez yapmak yerine saklanan yanıtı döndürür. Sunucu hatası da saklanır: 500'den sonra işi yeniden çalıştırmak için yeni bir anahtar gönderin.
- **X-Http-Method-Override**: Yalnızca GET ve POST'a izin veren bir vekil sunucunun arkasındaki çağıranlar için. `POST` ile gönderildiğinde değer metodun yerine geçer; başka bir metotta başlık yok sayılır, yani GET, GET olarak kalır.

### Zarf

Başarı `data` taşır; içerik hakkında söylenecek bir şey varsa yanında `meta` gelir. Başarısızlık ise sabit bir `code`, insanın okuyacağı bir mesaj ve doğrulama hatalarında alanları adıyla veren bir `details` eşlemesi taşır.

```json
{ "data": { "id": 42, "email": "ada@example.com" } }

{ "data": [ ], "meta": { "total": 318, "page": 2, "limit": 25, "next_page": 3 } }

{ "error": { "code": "validation_failed", "message": "Email is not valid.",
             "details": { "email": "invalid_format" } } }
```

Metne göre değil anahtara göre dallanın. `code` sözleşmenin parçası ve yerinde kalır; `message` kayıt okuyan bir insan için yazılmıştır ve yeniden ifade edilebilir.

### Durum Kodları

- **200 · 201**: Tamam. Oluşturma 201 ile cevap verir ve yeni kaydı döndürür.
- **401**: Anahtar yok ya da kurulumun tanımadığı bir anahtar. Kimlik bilgisini düzeltin; yeniden denemek işe yaramaz.
- **403**: Anahtar tanınıyor ama buraya izinli değil: yanlış adres, eksik izin ya da demo kipi açıkken yazma denemesi.
- **404**: Böyle bir uç yok ya da bu anahtar için böyle bir kayıt yok. Müşteri adresinde başkasına ait kayıt da aynı cevabı alır.
- **409**: Aynı `Idempotency-Key` ile bir istek hâlâ sürüyor. Bekleyip yeniden deneyin.
- **413**: Gövde sunucunun yükleme sınırını aştı. Kaynağa hiç ulaşmadı, dolayısıyla hiçbir şey kaydedilmedi.
- **422**: Girdi anlaşıldı ve reddedildi. `details` alanları adıyla verir.
- **429**: Çok fazla istek. `Retry-After` süresine uyun.
- **500**: Karşı tarafta bir şey hata verdi. Ayrıntı yanıtta değil, operatörün hata kaydında durur.

### Sayfalama

Liste uçları sorgu dizesinde `page` ve `limit` alır. `limit` varsayılan 25, tavanı 100; daha fazlasını istemek sessizce 100 verir. Sayfaları `meta.next_page` ile gezin; son sayfada değeri `0` olur.

Kaydırma tabanlı sayfalama v1 sözleşmesidir. İmleç tabanlı sayfalama yalnız veri bir zaman akışı olduğunda kullanılır, örneğin talep mesajlarında; o uçlar kendi imleç alanlarını kendileri anlatır.

### Yanıt Başlıkları

Kimlik isteyen her yanıt bütçenizin durumunu bildirir, böylece tahminle değil ölçerek hız ayarlarsınız.

- **X-RateLimit-Limit**: Bu dakikalık pencerede izin verilen istek sayısı.
- **X-RateLimit-Remaining**: Ondan geriye kalan.
- **X-RateLimit-Reset**: Pencerenin yenileneceği an, Unix zamanı olarak.
- **Idempotency-Replayed**: Yanıt taze işten değil kayıttan geldiğinde bulunur.

## Örnek

```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients' \
     -H 'Authorization: Bearer wak_...' \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: signup-8f21c0' \
     -d '{"name":"Ada","surname":"Lovelace","email":"ada@example.com"}'
# 201  {"data":{"id":91,...}}

# aynı çağrı tekrar aynı gövdeyi döndürür ve ikinci bir müşteri oluşturmaz
# 201  Idempotency-Replayed: true
```

## Tuzaklar

> **Toplamlar kökte değil meta altında**
> 
> Liste yanıtı sayısını `meta.total` içinde tutar. `total` değerini kökten okumak size hiçbir şey vermez ve hata da üretmez; sonuç boş bir küme gibi görünür. Aynısı `page` ve `limit` için de geçerli.

> **Demo kipi her yazmayı reddeder**
> 
> Kurulum demo kipindeyken POST, PUT, PATCH ve DELETE herhangi bir kaynağa ulaşmadan `403 demo_mode` ile döner. Okumalar çalışmaya devam eder, demo API üzerinden gezilebilir kalır. Yalnızca yazmalarda hata veren bir entegrasyonda önce buraya bakmaya değer.

## İlgili Makaleler

- [WISECP API'si](https://dev.wisecp.com/tr/wisecp-apisi)
- [API Kimlik Doğrulama ve İzinler](https://dev.wisecp.com/tr/api-kimlik-dogrulama-ve-izinler)
- [API Kaynakları](https://dev.wisecp.com/tr/api-kaynaklari)