{"id":184,"date":"2026-11-09T06:52:00","date_gmt":"2026-11-09T06:52:00","guid":{"rendered":"https:\/\/www.akifsen.com.tr\/blog\/?p=184"},"modified":"2026-11-09T06:52:00","modified_gmt":"2026-11-09T06:52:00","slug":"batch-api-design-partial-failure","status":"publish","type":"post","link":"https:\/\/www.akifsen.com.tr\/blog\/2026\/11\/09\/batch-api-design-partial-failure\/","title":{"rendered":"Toplu \u0130\u015flem Endpoint&#8217;leri: Batch API Nas\u0131l Tasarlan\u0131r?"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">Bir m\u00fc\u015fteri CRM&#8217;ine 10 bin ki\u015fi aktarmak istiyor.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">API&#8217;de sadece tekil olu\u015fturma endpoint&#8217;i var:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>POST \/api\/contacts<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">10 bin istek. Her biri 80 ms. S\u0131rayla g\u00f6nderildi\u011finde 13 dakikadan fazla. Paralel g\u00f6nderildi\u011finde ise rate limit&#8217;e tak\u0131l\u0131yor.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Toplu bir endpoint gerekiyor.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Atomik mi, k\u0131smi mi?<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Batch endpoint tasar\u0131m\u0131nda ilk soru \u015fu: 500 kay\u0131ttan biri hatal\u0131ysa ne olacak?<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Atomik:<\/strong> Ya hepsi olu\u015fturulur ya hi\u00e7biri. Tek bir hatal\u0131 kay\u0131t b\u00fct\u00fcn iste\u011fi reddeder.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>K\u0131smi ba\u015far\u0131:<\/strong> Ge\u00e7erli kay\u0131tlar olu\u015fturulur, hatal\u0131 olanlar raporlan\u0131r.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Atomik yakla\u015f\u0131m basit ve \u00f6ng\u00f6r\u00fclebilir. Client i\u00e7in sonu\u00e7 nettir. Ama 500 kay\u0131ttan birindeki hatal\u0131 bir e-posta adresi y\u00fcz\u00fcnden 499 ge\u00e7erli kayd\u0131n reddedilmesi, kullan\u0131c\u0131 i\u00e7in sinir bozucu olabilir.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">K\u0131smi ba\u015far\u0131 daha kullan\u0131\u015fl\u0131 ama client&#8217;\u0131n her kayd\u0131n sonucunu ayr\u0131 ayr\u0131 i\u015flemesini gerektirir.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Do\u011fru se\u00e7im kullan\u0131m senaryosuna ba\u011fl\u0131. Bir sipari\u015fin kalemleri birlikte anlaml\u0131d\u0131r, atomik olmal\u0131. Ba\u011f\u0131ms\u0131z ki\u015fi kay\u0131tlar\u0131 ise k\u0131smi ba\u015far\u0131ya uygundur.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Baz\u0131 API&#8217;ler bunu client&#8217;a b\u0131rak\u0131r:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>POST \/api\/contacts:batchCreate?atomic=true<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Cevap format\u0131<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">K\u0131smi ba\u015far\u0131da her kayd\u0131n sonucu, istek i\u00e7indeki s\u0131ras\u0131yla e\u015fle\u015ftirilebilir \u015fekilde d\u00f6nmeli:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>{\n  \"results\": [\n    { \"index\": 0, \"status\": \"created\", \"id\": \"c_8812\" },\n    { \"index\": 1, \"status\": \"created\", \"id\": \"c_8813\" },\n    { \"index\": 2, \"status\": \"error\",\n      \"error\": { \"code\": \"invalid_email\", \"field\": \"email\" } }\n  ],\n  \"summary\": { \"created\": 2, \"failed\": 1 }\n}<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Client hangi kay\u0131tlar\u0131n ba\u015far\u0131s\u0131z oldu\u011funu ve nedenini bilir. Sadece onlar\u0131 d\u00fczeltip tekrar g\u00f6nderebilir.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">HTTP status code se\u00e7imi tart\u0131\u015fmal\u0131. Baz\u0131 API&#8217;ler k\u0131smi ba\u015far\u0131da <code>200<\/code> d\u00f6ner ve detay\u0131 g\u00f6vdeye b\u0131rak\u0131r. Baz\u0131lar\u0131 WebDAV&#8217;dan gelen <code>207 Multi-Status<\/code> kullan\u0131r. Hangisi se\u00e7ilirse se\u00e7ilsin, tutarl\u0131 olmak ve belgelemek \u00f6nemli. Client, sadece status code&#8217;a bakarak b\u00fct\u00fcn kay\u0131tlar\u0131n ba\u015far\u0131l\u0131 oldu\u011funu varsaymamal\u0131.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Tekrarlanan istek<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Bir batch iste\u011fi timeout ald\u0131. Client tekrar g\u00f6nderdi.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Kay\u0131tlar\u0131n bir k\u0131sm\u0131 ilk istekte olu\u015fturulmu\u015fsa, ikinci istekte tekrar olu\u015fturulur.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Batch i\u015flemlerde idempotency daha da \u00f6nemli. \u0130ste\u011fin tamam\u0131 i\u00e7in bir idempotency key veya her kay\u0131t i\u00e7in client&#8217;\u0131n \u00fcretti\u011fi bir referans, tekrar g\u00f6nderimde kopya olu\u015fmas\u0131n\u0131 engeller.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">S\u0131n\u0131rlar<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Bir batch endpoint&#8217;i s\u0131n\u0131rs\u0131z boyutta istek kabul etmemeli.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>max 500 items per request\nmax 5 MB body<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">\u00c7ok b\u00fcy\u00fck istekler uzun s\u00fcren transaction&#8217;lar, bellek bask\u0131s\u0131 ve timeout&#8217;lar demek. S\u0131n\u0131r\u0131 a\u015fan istekler <code>413<\/code> ile reddedilir ve client par\u00e7alara b\u00f6lerek g\u00f6nderir.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Daha b\u00fcy\u00fck hacimler i\u00e7in, \u00f6rne\u011fin 1 milyon kay\u0131t, senkron bir batch endpoint yerine dosya y\u00fckleme ve asenkron i\u015fleme daha uygun. Client bir CSV dosyas\u0131 y\u00fckler, bir i\u015f ba\u015flat\u0131l\u0131r, sonu\u00e7 bir rapor olarak sunulur.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Rate limiting<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Batch endpoint&#8217;leri tekil endpoint&#8217;lerle ayn\u0131 rate limit&#8217;e tabi tutmak yanl\u0131\u015f sonu\u00e7 verir. 500 kay\u0131tl\u0131k bir istek, 1 kay\u0131tl\u0131k bir istekle ayn\u0131 maliyette de\u011fildir.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Rate limit&#8217;i istek say\u0131s\u0131 yerine kay\u0131t say\u0131s\u0131 \u00fczerinden hesaplamak, batch endpoint&#8217;inin limitleri a\u015fman\u0131n bir yolu olarak kullan\u0131lmas\u0131n\u0131 engeller.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Batch endpoint&#8217;ler performans i\u00e7in eklenir.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Ama as\u0131l tasar\u0131m zorlu\u011fu performans de\u011fil, i\u015fler k\u0131smen ters gitti\u011finde client&#8217;a ne s\u00f6ylenece\u011fi.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Bin kayd\u0131 tek tek g\u00f6ndermek yava\u015f, tek istekte g\u00f6ndermek ise k\u0131smi hata sorusunu getiriyor. Batch endpoint tasar\u0131m\u0131nda atomiklik, k\u0131smi ba\u015far\u0131 ve s\u0131n\u0131rlar.<\/p>\n","protected":false},"author":1,"featured_media":183,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[9],"tags":[],"class_list":["post-184","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-api-tasarimi"],"_links":{"self":[{"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/posts\/184","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/comments?post=184"}],"version-history":[{"count":1,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/posts\/184\/revisions"}],"predecessor-version":[{"id":234,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/posts\/184\/revisions\/234"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/media\/183"}],"wp:attachment":[{"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/media?parent=184"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/categories?post=184"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/tags?post=184"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}