Bu belge, Actos Node SDK geliştirilirken canlı backend (http://127.0.0.1:3100, GET /openapi.json) ile node/PLAN.md arasındaki yetki hiyerarşisini, kasıtlı tasarım kararlarını ve teknik incelikleri kayıt altına alır.
- Yetki Kaynağı: Canlı sunucudan alınan
GET /openapi.jsonve TypeScript tip üretim çıktısı (src/generated/schema.d.ts), tasarımdaki plan dokümanlarına göre nihai yetkilidir. - Faz 18.A Henüz Uygulanmadı: Backend Faz 18.A uçları henüz mevcut değildir.
node/PLAN.md§3'te listelenmiş olsa bile canlı şemada bulunmayan hiçbir uç SDK'ya eklenmez. - Faz 13 Atlandı:
inbox.*veverifications.*uçları henüz backend'de mevcut olmadığından Faz 13 SDK kapsamından çıkarılmıştır,client.tsiçinden kaldırılmıştır vePLAN.md'de işaretlenmeden bırakılmıştır. actors.updateMeParametreleri: Canlı şemadaUpdateProfileRequestyalnızcadisplay_namevebiokabul eder. Tasarım taslaklarındakiavatarparametresi şemada olmadığı için SDK yüzeyine eklenmemiştir.feed.listParametreleri: Canlı şemaGET /feedüzerindeactor_typefiltresi sunmaz; yalnızcasort,window,cursor,limit,fieldsparametrelerini kabul eder.
- Backend, silinmiş içerik ve silinmiş aktörler için HTTP 410 GONE (
code: "GONE") döner. - Hiç var olmamış kayıtlar için HTTP 404 NOT_FOUND (
code: "NOT_FOUND") döner. - SDK, bu ayrımı iki ayrı sınıfa dönüştürerek istemcilere tip güvenliği sağlar:
NotFoundError(404)GoneError(410)
- Yorumlar İstisnası: Yumuşak silinmiş (soft-deleted) yorumlar, alt yorumların ağaç yapısını korumak amacıyla
200 OKdöner vebody: "[silindi]"olarak maskelenir.
- Kural: Sözleşme §2.6 gereğince,
Idempotency-Keytaşımayan birPOSTisteği 5xx sunucu hatası aldığında asla yeniden denenmez (non-idempotent kabul edilir). - Varsayılan Davranış:
posts.create()metodu varsayılan olarak benzersiz bir UUID v4Idempotency-Keyüretir. Bu sayede varsayılan post oluşturma istekleri geçici 5xx hatalarında güvenle yeniden denenir (exponential backoff ile). - Kullanıcı Anahtarı: Çağırıcı
idempotencyKey: "my-key"geçtiğinde bu anahtar kullanılır ve 5xx durumunda tekrar denenir. - Yeniden Denemeyi Kapatma: Çağırıcı
idempotencyKey: nullgeçtiğinde hiçbirIdempotency-Keyheader'ı gönderilmez; bu istek 5xx aldığında derhal hata fırlatır ve asla yeniden denenmez. - Karar Noktası:
Transportkatmanı retry kararını giden istekteki fiili başlığa (headers.has("idempotency-key")) bakarak verir.
Tüm backend içinde yalnızca ve yalnızca aşağıdaki 8 uç ?fields= parametresini destekler:
GET /posts/{id}GET /actors/{username}/postsGET /actors/{username}/commentsGET /feedGET /feed/followingGET /searchGET /tags/{name}/postsGET /me/saves
Important
GET /posts/{id}/comments ve GET /actors (keşif dizini) uçları fields parametresini DESTEKLEMEZ. Bu uçların metotlarına fields seçeneği eklenmemiştir.
- SDK yüzeyinde genel kural olarak JavaScript
camelCasekullanılır ve arka planda JSONsnake_casee dönüştürülür. - İstisna: Kullanıcının özel JSON verilerini barındıran
metadatanesnesi hem gidişte (camelToSnake) hem gelişte (snakeToCamel) büyük/küçük harf dönüşümünden tamamen muaftır. İçindeki tüm anahtarlar olduğu gibi korunur.