Kayıt oluşturulduğunda istemciye ne dönmelisiniz?
201 Created, isteğin yerine getirildiğini ve bir veya daha fazla yeni kaynak oluştuğunu bildirir. Bir not oluşturma API'sinde yalnızca “başarılı” demek yerine yeni kaydın kimliğini ve adresini vermek, istemcinin sonraki adımını belirginleştirir. MDN 201 referansı bu durum kodunu örnekler.
Bu yazıdaki /api/notes adresleri kurgusal bir API sözleşmesidir. Kodları bir sayfaya yapıştırmak sunucu veya veri saklama katmanı oluşturmaz. Örnekte kayıt oluşturma tamamlanır; bir işi sıraya alma akışı anlatılmıyor.
Oluşturma yanıtında adresi açıkça verin
POST /api/notes HTTP/1.1
Host: example.test
Content-Type: application/json
Accept: application/json
{"title":"Notes"}
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/notes/73
Content-Location: /api/notes/73
Cache-Control: no-store
{"id":73,"title":"Notes"}
Genel sunucu ve mesaj çerçeveleme başlıkları okunabilirlik için kısaltıldı. Bu sözleşmede Location yeni notun adresidir. Gövde de notun kendi gösterimi olduğu için Content-Location aynı adresi gösterir. Yanıt JSON'u yalnızca bir işlem makbuzu olsaydı onu otomatik olarak notun gösterimi saymamalıydık.
Location zorunlu olarak mutlak URL değildir. Başında / bulunan bu değer, isteğin origin'ine göre çözülür. Location belgesi göreli adresleri de kapsar. Genel HTTP kuralında Location yoksa oluşturulan birincil kaynağı hedef URI tanımlar; bu örnekteki koleksiyona POST sözleşmesi ise yeni üyeyi açıkça göstermek için Location istiyor.
Location tarayıcıyı kendi başına yönlendirmez
201 bir yönlendirme kodu değildir. fetch, yalnızca Location gördüğü için bu adrese yeni GET yapmaz; yanıtın URL'si de kendiliğinden yeni not adresine dönüşmez. İstemci gövdedeki notla listeyi güncelleyebilir veya ihtiyaç duyarsa adresi daha sonra okuyabilir.
GET /api/notes/73 HTTP/1.1
Host: example.test
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{"id":73,"title":"Notes"}
Kullanıcıyı bir HTML sonuç sayfasına göndermek ayrı bir tasarım kararıdır. Örneğin POST sonrasında 303 ile GET akışı kurulabilir; 303, 307 ve 308 yazısı yöntem farklarını açıklar. API yanıtında 201 kullanıp arayüzün gezinmesini ayrıca yönetmek de mümkündür.
İstemcide beklenen sözleşmeyi doğrulayın
Aşağıdaki yardımcı, aynı origin'de çalışan örnek API için yazıldı. Dönen notu ve çözümlenmiş adresi verir; ikinci bir istek veya sayfa geçişi yapmaz.
async function createNote(title) {
if (typeof title !== 'string' || title.trim() === '') {
throw new TypeError('A non-empty title is required');
}
const endpoint = new URL('/api/notes', location.origin);
const response = await fetch(endpoint, {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({ title: title.trim() }),
});
if (response.status !== 201) {
throw new Error('Expected a completed resource creation');
}
const target = response.headers.get('Location');
if (!target) throw new Error('The resource address is missing');
const resourceURL = new URL(target, response.url || endpoint.href);
if (resourceURL.origin !== endpoint.origin) {
throw new Error('Unexpected resource origin');
}
const note = await response.json();
return { note, url: resourceURL.href };
}
response.ok yerine tam durum koduna bakmak burada bilinçli bir seçim: Yardımcının sözleşmesi 201 bekliyor. Genel amaçlı her API istemcisi için yalnızca 201 kabul edin demiyoruz. Gerçek uygulamada dönen JSON'un şemasını da doğrulayın ve hata gövdelerini Problem Details yaklaşımıyla ele alın.
Farklı origin'deki API'den Location okumak için sunucunun CORS politikasında Access-Control-Expose-Headers ile bu başlığı açması gerekebilir; Location varsayılan olarak JavaScript'e açılan yanıt başlıklarından değildir. Bu yardımcı aynı origin varsaydığı için CORS yapılandırması eklemiyor.
201 ile 202 arasındaki ürün kararını verin
Not kaydı oluşmuş ama e-posta bildirimi bekliyorsa notun oluşturulması için 201 hâlâ anlamlı olabilir. Kaynağın oluşması henüz tamamlanmadıysa bunu olmuş gibi sunmayın. 202 Accepted rehberi iş durumu ve izleme adresi tasarımını inceler.
Ağ kesintisi yüzünden yanıtı görememek, kaydın oluşmadığını kanıtlamaz. 201 kodu da tekrar gönderilen POST'ları otomatik olarak tekilleştirmez. Yeniden deneme politikasını backoff ve güvenli tekrar yazısıyla birlikte değerlendirin.
Sık sorulan sorular
201 yalnızca POST için mi kullanılır? Hayır. Yeni bir hedef oluşturan başarılı PUT da 201 döndürebilir; mevcut hedefi güncellemek başka bir durumdur.
Gövde her zaman zorunlu mu? Hayır. Bu örnek istemciye gösterilecek kaydı JSON olarak döndürmeyi seçiyor.
Content-Location, Location yerine geçer mi? Hayır. İlki yanıttaki gösterimin adresini, ikincisi bu 201 sözleşmesinde oluşturulan birincil kaynağın adresini anlatır. Content-Location referansı ayrımı açıklar; RFC 9110 durum kodunun standart tanımıdır.

