Mobil REST API tasarımı: endpoint, hata, sayfalama ve sürümleme

Kimler için?

Kendi Node.js, Laravel veya Python backend’ini tasarlayan mobil geliştiriciler.

Başlamadan önce

Bir örnek veri modeli, kullanıcı rolleri ve API’ye ait bir staging ortamı.

1. Kaynak ve yetki sınırını tanımlayın

Endpoint’i veritabanı tablosunun birebir kopyası olarak düşünmeyin. İstemcinin yapabileceği işlemi ve kullanıcının o kaynak üzerindeki yetkisini açıkça tanımlayın. /projects/{id}/notes gibi bir adreste proje kimliği yetki anlamına gelmez. Sunucu oturumdan kullanıcıyı bulmalı ve proje üyeliğini doğrulamalıdır. Kullanıcının gönderdiği owner_id alanı bu kontrolün yerine geçmez.

2. Yanıtı uygulamanın ihtiyacına göre sınırlayın

Liste ekranı için bütün kayıtların ayrıntısını indirmek yerine gerekli alanları döndürün. Sıralama kararlı olmalı; cursor benzersiz bir sonlandırıcı içermelidir. Limit için sunucu üst sınırı koyun. Offset küçük veri setlerinde yeterli olabilir; büyük ve sürekli değişen listelerde cursor yaklaşımı daha tutarlı bir ilerleme sağlar.

GET /v1/notes?limit=20&after=opaque-cursor
{ "items": [{ "id": "note-42", "title": "Taslak" }],
  "next_cursor": "opaque-next", "has_more": true }

3. Hata sözleşmesini kararlı yapın

İstemci ekranda ne yapacağını insan dilindeki hata metnini ayrıştırarak belirlememelidir. Kararlı bir hata kodu, HTTP durumu ve güvenli bir açıklama döndürün. Beklenmeyen hata durumunda stack trace veya SQL metni açığa çıkmasın. İstek kimliği backend loguyla ilişki kurabilir; oturum tokenını aynı loga yazmayın.

4. Yazma işlemlerinin tekrarını tasarlayın

Ağ timeout’undan sonra sipariş veya dosya kayıt isteği tekrar gelebilir. Aynı mantıksal işlem için idempotency anahtarını koruyun. Anahtarın kullanıcı, işlem türü ve payload ile ilişkisini sunucuda doğrulayın; başka bir işlemde aynı anahtarın kullanımı sessizce başarılı sayılmamalıdır. GET ile veri okumak ve ödeme oluşturmak aynı retry politikasına sahip değildir.

5. Eski uygulama sürümlerini koruyun

Mobil uygulamayı tüm cihazlarda aynı gün güncelleyemezsiniz. Alan eklemek genellikle daha küçük değişikliktir; alan silmek, tip değiştirmek veya varsayılan davranışı bozmak sürüm planı gerektirir. API contract testlerinde eski istemci örneklerini tutun. Tarihleri ISO biçiminde, para tutarlarını açık para birimi ve minor unit ile taşıyın; yüzdelik veya tarih anlamını istemcinin tahmin etmesine bırakmayın.

6. Yayın kontrolü ve örneklerin sınırı

Bu sayfadaki endpoint’ler kendi API’niz için tasarım örnekleridir; Uygulama Cloud’un açık müşteri veri API’si değildir. Staging’de eksik token, başka kullanıcının kimliği, geçersiz cursor, aşırı limit ve tekrar anahtarı senaryolarını deneyin. OpenAPI belgesindeki alanların gerçek cevaba uyduğunu kontrol edin.

• Timeout ve maksimum payload için sınır koyun.
• Veri sahibi veya tenant sınırını her işlemde doğrulayın.
• Hata metinlerinde sır ve kişisel veri sızdırmayın.
• Eski istemci için geriye uyumluluk testini yayın kriteri yapın.