RESTful web API'si tasarımı için en iyi yöntemler

2025-04-10

RESTful web API'si uygulaması, istemci ve hizmet arasında durum bilgisi olmayan, gevşek bir şekilde bağlanmış bir arabirim elde etmek için Temsili Durum Aktarımı (REST) mimari ilkelerini kullanan bir web API'sidir. RESTful olan bir web API'si, kaynaklar üzerinde işlem gerçekleştirmek ve hipermedia bağlantıları ve HTTP işlem durum kodları içeren kaynakların gösterimlerini döndürmek için standart HTTP protokolünü destekler.

RESTful web API'sinin aşağıdaki ilkelerle uyumlu olması gerekir:

Platform bağımsızlığı, istemcilerin iç uygulamadan bağımsız olarak web API'sini çağırabileceği anlamına gelir. Platform bağımsızlığını elde etmek için web API'sinde standart protokol olarak HTTP kullanılır, net belgeler sağlanır ve JSON veya XML gibi tanıdık bir veri değişimi biçimi desteklenir.
Gevşek bağlantı, istemci ve web hizmetinin bağımsız olarak gelişebileceği anlamına gelir. İstemcinin web hizmetinin iç uygulamasını bilmesi ve web hizmetinin istemcinin iç uygulamasını bilmesi gerekmez. RESTful web API'sinde gevşek bağlantı sağlamak için yalnızca standart protokolleri kullanın ve istemcinin ve web hizmetinin değiş tokuş için verilerin biçimini kabul etmesini sağlayan bir mekanizma uygulayın.

Bu makalede RESTful web API'lerini tasarlamaya yönelik en iyi yöntemler açıklanmaktadır. Ayrıca anlaşılması kolay, esnek ve sürdürülebilir web API'leri oluşturmaya yönelik yaygın tasarım desenlerini ve dikkat edilmesi gerekenleri kapsar.

RESTful web API'si tasarım kavramları

RESTful web API'sini uygulamak için aşağıdaki kavramları anlamanız gerekir.

Tekdüzen Kaynak Tanımlayıcısı (URI): REST API'leri, istemcinin erişebileceği her tür nesne, veri veya hizmet olan kaynaklar etrafında tasarlanmıştır. Her kaynak, bu kaynağı benzersiz olarak tanımlayan bir URI ile temsil edilir. Örneğin, belirli bir müşteri siparişi için URI şu olabilir:
```
https://api.contoso.com/orders/1
```
Kaynak gösterimi , URI'siyle tanımlanan bir kaynağın HTTP protokolü üzerinden XML veya JSON gibi belirli bir biçimde nasıl kodlandığını ve taşındığını tanımlar. Belirli bir kaynağı almak isteyen istemcilerin API isteğinde kaynağın URI'sini kullanması gerekir. API, URI'nin gösterdiği verilerin kaynak gösterimini döndürür. Örneğin, bir istemci aşağıdaki JSON gövdesini almak için URI tanımlayıcısına https://api.contoso.com/orders/1 get isteğinde bulunabilir:
```
{"orderId":1,"orderValue":99.9,"productId":1,"quantity":1}
```
Tekdüzen arabirim , RESTful API'lerinin istemci ve hizmet uygulamaları arasında gevşek bağlama gerçekleştirme yöntemidir. HTTP üzerinde oluşturulan REST API'ler için tekdüzen arabirim, kaynaklarda , GET, POST, PUTve PATCH gibi DELETEişlemleri gerçekleştirmek için standart HTTP fiilleri kullanmayı içerir.
Durum bilgisi olmayan istek modeli: RESTful API'leri durum bilgisi olmayan bir istek modeli kullanır. Bu, HTTP isteklerinin bağımsız olduğu ve herhangi bir sırada gerçekleşebileceği anlamına gelir. Bu nedenle, istekler arasında geçici durum bilgilerini tutmak mümkün değildir. Bilgilerin depolandığı tek yer kaynaklardır ve her istek atomik bir işlem olmalıdır. Durum bilgisi olmayan istek modeli, istemciler ve belirli sunucular arasında herhangi bir benşim koruması gerekmediğinden yüksek ölçeklenebilirliği destekler. Ancak durum bilgisi olmayan model, web hizmeti arka uç depolama ölçeklenebilirliğiyle ilgili zorluklar nedeniyle ölçeklenebilirliği de sınırlayabilir. Veri deposu ölçeğini genişletme stratejileri hakkında daha fazla bilgi için bkz. Veri bölümleme.
Hypermedia bağlantıları: REST API'leri, her kaynak gösteriminde yer alan hipermedia bağlantıları tarafından yönlendirilebilir. Örneğin, aşağıdaki kod bloğu bir siparişin JSON gösterimini gösterir. Siparişle ilişkili müşteriyi almak veya güncelleştirmek için bağlantılar içerir.
```
{
  "orderID":3,
  "productID":2,
  "quantity":4,
  "orderValue":16.60,
  "links": [
    {"rel":"product","href":"https://api.contoso.com/customers/3", "action":"GET" },
    {"rel":"product","href":"https://api.contoso.com/customers/3", "action":"PUT" }
  ]
}
```

RESTful web API kaynak URI'lerini tanımlama

RESTful web API'leri kaynaklar etrafında düzenlenir. API tasarımınızı kaynaklara göre düzenlemek için iş varlıklarıyla eşleşen kaynak URI'lerini tanımlayın. Mümkün olduğunda, temel kaynak URI'leri fiillere (kaynak üzerindeki işlemler) değil, isimlere (kaynak) dayandırın.

Örneğin, bir e-ticaret sisteminde birincil iş varlıkları müşteriler ve siparişler olabilir. Bir sipariş oluşturmak için istemci, HTTP POST isteğindeki sipariş bilgilerini kaynak URI'sine gönderir. İsteğin HTTP yanıtı, sipariş oluşturma işleminin başarılı olup olmadığını gösterir.

Sipariş kaynağını oluşturmak için URI şöyle olabilir:

https://api.contoso.com/orders // Good

İşlemleri göstermek için URI'lerde fiil kullanmaktan kaçının. Örneğin, aşağıdaki URI önerilmez:

https://api.contoso.com/create-order // Avoid

Varlıklar genellikle müşteriler veya siparişler gibi koleksiyonlar halinde gruplandırılır. Koleksiyon, koleksiyonun içindeki öğelerden ayrı bir kaynak olduğundan kendi URI'sine sahip olması gerekir. Örneğin, aşağıdaki URI sipariş koleksiyonunu temsil edebilir:

https://api.contoso.com/orders

İstemci koleksiyonu aldıktan sonra, her öğenin URI'sine bir GET isteğinde bulunabilir. Örneğin, belirli bir siparişle ilgili bilgi almak için istemci, iç sipariş verilerinin kaynak gösterimi olarak aşağıdaki JSON gövdesini almak için URI'de https://api.contoso.com/orders/1 bir HTTP GET isteği gerçekleştirir:

{"orderId":1,"orderValue":99.9,"productId":1,"quantity":1}

Kaynak URI adlandırma kuralları

RESTful web API'sini tasarlarken kaynaklar için doğru adlandırma ve ilişki kurallarını kullanmanız önemlidir:

Kaynak adları için isim kullanın. Kaynakları temsil etmek için isimleri kullanın. Örneğin, /orders yerine /create-order kullanın. HTTP GET, POST, PUT, PATCH ve DELETE yöntemleri zaten sözel eylemi ifade eder.
Koleksiyon URI'lerini adlandırmak için çoğul isimleri kullanın. Genel olarak, koleksiyonlara başvuran URI'ler için çoğul isimlerin kullanılmasına yardımcı olur. Koleksiyonlar ve öğeler için URI'leri bir hiyerarşide düzenlemek iyi bir uygulamadır. Örneğin, /customers müşterinin koleksiyonunun yolu ve /customers/5 5'e eşit bir kimliğe sahip müşterinin yoludur. Bu yaklaşım web API'sinin sezgisel kalmasına yardımcı olur. Ayrıca, birçok web API çerçevesi istekleri parametreli URI yollarına göre yönlendirebilir, böylece yolu /customers/{id}için bir yol tanımlayabilirsiniz.
Farklı kaynak türleri arasındaki ilişkileri ve bu ilişkilendirmeleri nasıl ortaya çıkarabileceğinizi düşünün. Örneğin, /customers/5/orders müşteri 5 için tüm siparişleri temsil edebilir. Ayrıca, bir siparişten müşteriye olan ilişkiyi temsil ederek ilişkiye başka bir yönde de yaklaşabilirsiniz. Bu senaryoda, URI olabilir /orders/99/customer. Ancak, bu modelin çok fazla genişletilmesi, uygulanamayacak kadar hantal hale gelebilir. İstemcilerin ilgili kaynaklara kolayca erişebilmesi için HTTP yanıt iletisinin gövdesine bağlantılar eklemek daha iyi bir yaklaşımdır. İlgili kaynaklara gezintiyi etkinleştirmek için Uygulama Durumunun Motoru olarak Hypertext'i (HATEOAS) kullanın. Bu mekanizma daha ayrıntılı olarak açıklanmaktadır.
İlişkileri basit ve esnek tutun. Daha karmaşık sistemlerde, istemcinin gibi /customers/1/orders/99/productsçeşitli ilişki düzeylerinde gezinmesine izin veren URI'ler sağlamaya eğilimli olabilirsiniz. Ancak, bu karmaşıklık düzeyini korumak zor olabilir ve gelecekte kaynaklar arasındaki ilişkiler değişirse esnek değildir. Bunun yerine, URI'leri nispeten basit tutmaya çalışın. Bir uygulamanın bir kaynağa referansı olduğunda, bu referansı kullanarak ilgili öğeleri bulabilmeniz gerekir. Müşteri 1'in tüm siparişlerini bulmak için önceki sorguyu URI /customers/1/orders ile değiştirebilir ve ardından bu siparişteki ürünleri bulmak için kullanabilirsiniz /orders/99/products .

İpucu

Koleksiyon/öğe/koleksiyondan daha karmaşık kaynak URI'leri gerektirmekten kaçının.
Çok fazla sayıda küçük kaynaktan kaçının. Tüm web istekleri web sunucusuna yük yükler. İstek sayısı ne kadar fazlaysa yük o kadar büyük olur. Çok sayıda küçük kaynağı kullanıma sunan web API'leri , gevevelemeli web API'leri olarak bilinir. Bu API'lerden kaçınmaya çalışın çünkü bir istemci uygulamasının ihtiyaç duydukları tüm verileri bulmak için birden çok istek göndermesini gerektirir. Bunun yerine, verileri normalden kaldırmayı ve ilgili bilgileri tek bir istekle alınabilecek daha büyük kaynaklarda birleştirmeyi göz önünde bulundurun. Ancak, yine de bu yaklaşımı istemcinin ihtiyaç duymadığı verileri getirme yüküne karşı dengelemeniz gerekir. Büyük nesne alma, isteğin gecikme süresini artırabilir ve daha fazla bant genişliği maliyetine neden olabilir. Bu performans antipatternleri hakkında daha fazla bilgi için bkz. Geveze G/Ç ve Gereksiz Getirme.
Veritabanının iç yapısını yansıtan API'ler oluşturmaktan kaçının. REST'in amacı, iş varlıklarını ve bir uygulamanın bu varlıklar üzerinde gerçekleştirebileceği işlemleri modellemektir. İstemcinin iç uygulamaya açık olmaması gerekir. Örneğin, verileriniz ilişkisel bir veritabanında depolanıyorsa web API'sinin her tabloyu bir kaynak koleksiyonu olarak kullanıma sunması gerekmez. Bu yaklaşım saldırı yüzeyini artırır ve veri sızıntısına neden olabilir. Bunun yerine, web API'sini veritabanının soyutlaması olarak düşünün. Gerekirse, veritabanı ve web API'si arasında bir eşleme katmanı tanıtın. Bu katman, istemci uygulamalarının temel alınan veritabanı şemasındaki değişikliklerden yalıtılmasını sağlar.

İpucu

Bir web API'si tarafından uygulanan her işlemi belirli bir kaynakla eşlemek mümkün olmayabilir. Bu kaynak olmayan senaryoları, bir işlevi çağıran ve sonuçları HTTP yanıt iletisi olarak döndüren HTTP istekleri aracılığıyla işleyebilirsiniz.

Örneğin, ekleme ve çıkarma gibi basit hesap makinesi işlemleri uygulayan bir web API'leri, bu işlemleri sahte kaynak olarak kullanıma sunan ve sorgu dizesini kullanarak gerekli parametreleri belirten URI'ler sağlayabilir. /add?operand1=99&operand2=1 URI'sine yönelik bir GET isteği, gövdesi 100 değerini içeren bir yanıt iletisi döndürür.

Ancak, bu URI biçimlerini tedbirli bir şekilde kullanmanız gerekir.

RESTful web API yöntemlerini tanımlama

RESTful web API yöntemleri, HTTP protokolü tarafından tanımlanan istek yöntemleri ve medya türleriyle hizalanır. Bu bölümde, RESTful web API'lerinde kullanılan en yaygın istek yöntemleri ve medya türleri açıklanmaktadır.

HTTP isteği yöntemleri

HTTP protokolü, bir kaynakta gerçekleştirmek istediğiniz eylemi belirten birçok istek yöntemini tanımlar. RESTful web API'lerinde kullanılan en yaygın yöntemler GET, POST, PUT, PATCH ve DELETE'dir. Her yöntem belirli bir işleme karşılık gelir. RESTful web API'sini tasarlarken, bu yöntemleri protokol tanımı, erişilen kaynak ve gerçekleştirilen eylemle tutarlı bir şekilde kullanın.

Belirli bir istek yönteminin etkisinin kaynağın bir koleksiyon mu yoksa tek bir öğe mi olduğuna bağlı olması gerektiğini unutmayın. Aşağıdaki tablo, çoğu RESTful uygulamasının kullandığı bazı kuralları içerir.

Önemli

Aşağıdaki tabloda örnek bir e-ticaret customer varlığı kullanılır. Web API'sinin tüm istek yöntemlerini uygulaması gerekmez. Uyguladığı yöntemler belirli bir senaryoya bağlıdır.

Kaynak	PAYLAŞ	AL	KOYMAK	SİLMEK
/Müşteri	Yeni müşteri oluşturma	Tüm müşterileri alma	Müşterilerin toplu güncellemesi	Tüm müşterileri kaldırma
/customers/1	Hata	1. müşterinin ayrıntılarını alma	Varsa müşteri 1'in ayrıntılarını güncelleştirin	Müşteriyi kaldırma 1
/musteriler/1/siparisler	Müşteri 1 için yeni sipariş oluşturma	Müşteri 1 için tüm siparişleri alma	Müşteri 1 için siparişleri toplu güncelleştirme	Müşteri 1 için tüm siparişleri kaldırma

GET istekleri

GET isteği, belirtilen URI'de kaynağın bir gösterimini alır. Yanıt iletisinin gövdesi, istenen kaynağın ayrıntılarını içerir.

GET isteği aşağıdaki HTTP durum kodlarından birini döndürmelidir:

HTTP durum kodu	Nedeni
200 (Tamam)	yöntemi kaynağı başarıyla döndürdü.
204 (İçerik Yok)	Yanıt gövdesi, arama isteğinin HTTP yanıtında eşleşme döndürmemesi gibi herhangi bir içerik içermez.
404 (Bulunamadı)	İstenen kaynak bulunamıyor.

POST istekleri

POST isteği bir kaynak oluşturmalıdır. Sunucu yeni kaynak için bir URI atar ve bu URI'yi istemciye döndürür.

Önemli

POST isteklerinde istemci kendi URI'sini oluşturmaya çalışmamalıdır. İstemcinin isteği koleksiyonun URI'sine göndermesi ve sunucunun yeni kaynağa bir URI ataması gerekir. İstemci kendi URI'sini oluşturmayı dener ve belirli bir URI'ye post isteği gönderirse, sunucu yöntemin desteklenmediğini belirtmek için HTTP durum kodu 400 (BAD REQUEST) döndürür.

RESTful modelinde POST istekleri, URI'nin tanımlamış olduğu koleksiyona yeni bir kaynak eklemek için kullanılır. Ancak post isteği, yeni bir kaynak oluşturulmadan mevcut bir kaynağa işlenmek üzere veri göndermek için de kullanılabilir.

POST isteği aşağıdaki HTTP durum kodlarından birini döndürmelidir:

HTTP durum kodu	Nedeni
200 (Tamam)	yöntemi bazı işlemler yaptı ancak yeni bir kaynak oluşturmaz. İşlemin sonucu yanıt gövdesine eklenebilir.
201 (Oluşturuldu)	Kaynak başarıyla oluşturuldu. Yeni kaynağın URI'si yanıtın Konum üst bilgisine eklenir. Yanıt gövdesi kaynağın bir gösterimini içerir.
204 (İçerik Yok)	Yanıt gövdesi içerik içermiyor.
400 (Hatalı İstek)	İstemci isteğe geçersiz veri yerleştirmiş. Yanıt gövdesi hata hakkında daha fazla bilgi veya daha fazla ayrıntı sağlayan bir URI bağlantısı içerebilir.
405 (Yönteme İzin Verilmiyor)	İstemci, POST isteklerini desteklemeyen bir URI'ye POST isteğinde bulunmaya çalıştı.

PUT isteği

PUT isteği mevcut bir kaynağı varsa güncelleştirmeli veya bazı durumlarda mevcut değilse yeni bir kaynak oluşturmalıdır. PUT isteğinde bulunmak için:

İstemci, kaynağın URI'sini belirtir ve kaynağın tam bir gösterimini içeren bir istek gövdesi içerir.
İstemci isteği yapar.
Bu URI'ye sahip bir kaynak zaten varsa, yenisiyle değiştirilir. Aksi takdirde, yol destekliyorsa yeni bir kaynak oluşturulur.

PUT yöntemleri, koleksiyonlar yerine belirli bir müşteri gibi tek tek öğeler olan kaynaklara uygulanır. Sunucu güncelleştirmeleri desteklese de PUT aracılığıyla oluşturmayı desteklemiyor olabilir. PUT aracılığıyla oluşturmanın desteklenip desteklenmeyeceği, istemcinin var olmadan önce kaynağa anlamlı ve güvenilir bir şekilde URI atayıp atayamayacağına bağlıdır. Kaynak oluşturamıyorsa POST'u kullanarak kaynak oluşturun ve sunucunun URI'yi atamasını sağlayın. Ardından PUT veya PATCH kullanarak URI'yi güncelleştirin.

Önemli

PUT istekleri idempotent olmalıdır; başka bir deyişle, aynı isteğin birden çok kez gönderilmesi her zaman aynı kaynağın aynı değerlerle değiştirilmesiyle sonuçlanır. İstemci bir PUT isteğini yeniden gönderirse, sonuçlar değişmeden kalmalıdır. Buna karşılık, POST ve PATCH isteklerinin özdeş sonuç vereceği garanti edilmez.

PUT isteği aşağıdaki HTTP durum kodlarından birini döndürmelidir:

HTTP durum kodu	Nedeni
200 (Tamam)	Kaynak başarıyla güncelleştirildi.
201 (Oluşturuldu)	Kaynak başarıyla oluşturuldu. Yanıt gövdesi kaynağın bir gösterimini içerebilir.
204 (İçerik Yok)	Kaynak başarıyla güncelleştirildi, ancak yanıt gövdesi herhangi bir içerik içermiyor.
409 (Çakışma)	Kaynağın geçerli durumuyla çakışma nedeniyle istek tamamlanamadı.

İpucu

Bir koleksiyondaki birden çok kaynağa toplu güncelleştirmeler gerçekleştirebilen toplu HTTP PUT işlemlerini uygulamayı göz önünde bulundurun. PUT isteği koleksiyonun URI'sini belirtmelidir. İstek gövdesi, değiştirilecek kaynakların ayrıntılarını belirtmelidir. Bu yaklaşım sohbeti azaltmaya ve performansı artırmaya yardımcı olabilir.

PATCH istekleri

PATCH isteği, var olan bir kaynak için kısmi güncelleştirme gerçekleştirir. İstemci, kaynağın URI'sini belirtir. İstek gövdesi, kaynağa uygulanacak bir değişiklik kümesini belirtir. İstemci, kaynağın tüm gösterimini değil yalnızca değişiklikleri gönderdiğinden, bu yöntem PUT isteklerini kullanmaktan daha verimli olabilir. PATCH, sunucu bu eylemi destekliyorsa boş veya null bir kaynak için bir dizi güncelleştirme belirterek yeni bir kaynak da oluşturabilir.

PATCH isteğiyle, istemci mevcut bir kaynağa düzeltme eki belgesi biçiminde bir dizi güncelleştirme gönderir. Sunucu, güncelleştirmeyi gerçekleştirmek için düzeltme eki belgesini işler. Düzeltme eki belgesi, kaynağın tamamını tanımlamak yerine yalnızca uygulanacak bir değişiklik kümesini belirtir. PATCH yöntemi için RFC 5789 belirtimi, düzeltme eki belgeleri için belirli bir biçim tanımlamaz. Biçim, istekteki medya türünden çıkarılmalıdır.

JSON, web API'leri için en yaygın veri biçimlerinden biridir. JSON tabanlı iki ana düzeltme eki biçimi JSON düzeltme eki ve JSON birleştirme düzeltme ekidir.

JSON birleştirme yaması, JSON düzeltme ekinden daha basittir. Düzeltme eki belgesi özgün JSON kaynağıyla aynı yapıya sahiptir, ancak yalnızca değiştirilmesi veya eklenmesi gereken alanların alt kümesini içerir. Ayrıca, düzeltme belgesinde alan değeri olarak null belirtilirse bir alan silinebilir. Bu özellik, özgün kaynağın açık null değerler içerebileceği durumlarda birleştirme yamasının uygun olmadığını belirtir.

Örneğin, özgün kaynağın aşağıdaki JSON gösterimine sahip olduğunu varsayalım:

{
    "name":"gizmo",
    "category":"widgets",
    "color":"blue",
    "price":10
}

Bu kaynak için olası bir JSON birleştirme düzeltme eki aşağıdadır:

{
    "price":12,
    "color":null,
    "size":"small"
}

Bu birleştirme yaması sunucuya price güncellemesini, color silmesini ve size eklemesini söyler. name ve category değerleri değiştirilmez. JSON birleştirme düzeltme eki hakkında daha fazla bilgi için bkz. RFC 7396. JSON birleştirme yaması için medya türü application/merge-patch+json.

Orijinal kaynak, null'nın düzeltme belgesindeki özel anlamı nedeniyle açık null değerler içerebiliyorsa birleştirme düzeltmesi uygun değildir. Düzeltme eki belgesi, sunucunun güncelleştirmeleri uygulama sırasını da belirtmez. Bu siparişin önemli olup olmadığı verilere ve etki alanına bağlıdır. RFC 6902'de tanımlanan JSON düzeltme eki, değişiklikleri, değerleri doğrulamak için ekleme, kaldırma, değiştirme, kopyalama ve test etme gibi uygulanacak işlem dizisi olarak belirttiğinden daha esnektir. JSON yamasının medya türü application/json-patch+json.

PATCH isteği aşağıdaki HTTP durum kodlarından birini döndürmelidir:

HTTP durum kodu	Nedeni
200 (Tamam)	Kaynak başarıyla güncelleştirildi.
400 (Hatalı İstek)	Yanlış biçimlendirilmiş yama belgesi.
409 (Çakışma)	Düzeltme eki belgesi geçerlidir, ancak mevcut durumunda değişiklikler kaynağa uygulanamıyor.
415 (Desteklenmeyen Medya Türü)	Düzeltme eki belgesi biçimi desteklenmez.

DELETE istekleri

DELETE isteği, belirtilen URI'deki kaynağı kaldırır. DELETE isteği aşağıdaki HTTP durum kodlarından birini döndürmelidir:

HTTP durum kodu	Nedeni
204 (İÇERIK YOK)	Kaynak başarıyla silindi. İşlem başarıyla işlendi ve yanıt gövdesi başka bilgi içermiyor.
404 (BULUNAMADı)	Kaynak yok.

Kaynak MIME türleri

Kaynak gösterimi, URI tarafından tanımlanan bir kaynağın XML veya JSON gibi belirli bir biçimde HTTP protokolü üzerinden nasıl kodlandığı ve taşındığıdır. Belirli bir kaynağı almak isteyen istemcilerin API isteğinde URI'yi kullanması gerekir. API, URI tarafından belirtilen verilerin kaynak gösterimini döndürerek yanıt verir.

HTTP protokolünde, kaynak gösterimi biçimleri MIME türleri olarak da adlandırılan medya türleri kullanılarak belirtilir. Bire bir olmayan veriler için çoğu web API'sinde JSON (medya türü = application/json) ve muhtemelen XML (medya türü = application/xml) desteklenir.

İstek veya yanıttaki İçerik Türü üst bilgisi, kaynak gösterimi biçimini belirtir. Aşağıdaki örnekte JSON verilerini içeren bir POST isteği gösterilmektedir:

POST https://api.contoso.com/orders
Content-Type: application/json; charset=utf-8
Content-Length: 57

{"Id":1,"Name":"Gizmo","Category":"Widgets","Price":1.99}

Sunucu medya türünü desteklemiyorsa HTTP durum kodu 415 (Desteklenmeyen Medya Türü) döndürmelidir.

İstemci isteği, istemcinin yanıt iletisinde sunucudan kabul eden medya türlerinin listesini içeren bir Accept üst bilgisi içerebilir. Örneğin:

GET https://api.contoso.com/orders/2
Accept: application/json, application/xml

Sunucu listelenen medya türlerinden herhangi biriyle eşleşemiyorsa, 406 (Kabul Edilemez) HTTP durum kodunu döndürmelidir.

Zaman uyumsuz yöntemler uygulama

Bazen POST, PUT, PATCH veya DELETE yöntemi, tamamlanması zaman alan bir işleme gerektirebilir. İstemciye yanıt göndermeden önce tamamlanmasını beklerseniz, bu kabul edilemez gecikmeye neden olabilir. Bu senaryoda, yöntemi asenkron hale getirmeyi göz önünde bulundurun. Zaman uyumsuz bir yöntem, isteğin işlenmesi için kabul edildiği ancak tamamlanmadığını belirtmek için HTTP durum kodu 202 (Kabul Edildi) döndürmelidir.

İstemcinin durum uç noktasını sorgulayarak durumu izleyebilmesi için zaman uyumsuz bir isteğin durumunu döndüren bir uç nokta sağlayın. Durum uç noktasının URI'sini 202 yanıtının Konum üst bilgisine ekleyin. Örneğin:

HTTP/1.1 202 Accepted
Location: /api/status/12345

İstemci bu uç noktaya bir GET isteği gönderirse, yanıt isteğin geçerli durumunu içermelidir. İsteğe bağlı olarak, tahmini tamamlanma süresi veya işlemi iptal etmek için bir bağlantı içerebilir.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status":"In progress",
    "link": { "rel":"cancel", "method":"delete", "href":"/api/status/12345" }
}

Zaman uyumsuz işlem yeni bir kaynak oluşturursa, işlem tamamlandıktan sonra durum uç noktasının 303 (Diğer'e bakın) durum kodunu döndürmesi gerekir. 303 yanıtında, yeni kaynağın URI'sini veren bir Konum üst bilgisi ekleyin:

HTTP/1.1 303 See Other
Location: /api/orders/12345

Daha fazla bilgi için bkz. Uzun süre çalışan istekler için zaman uyumsuz destek sağlama ve Zaman uyumsuz Request-Reply düzeni.

Veri sayfalandırmayı ve filtrelemeyi uygulamak

Veri alımını iyileştirmek ve yük boyutunu azaltmak için API tasarımınızda veri sayfalaması ve sorgu tabanlı filtreleme uygulayın. Bu teknikler istemcilerin yalnızca ihtiyaç duydukları veri alt kümesini istemesine olanak tanır ve bu da performansı artırabilir ve bant genişliği kullanımını azaltabilir.

Sayfalandırma , büyük veri kümelerini daha küçük, yönetilebilir öbeklere böler. Döndürülecek öğe sayısını belirtmek ve limit başlangıç noktasını belirtmek için gibi offset sorgu parametrelerini kullanın. limit ve offset için, limit=25 ve offset=0 gibi anlamlı varsayılanlar sağladığınızdan emin olun. Örneğin:
```
GET /orders?limit=25&offset=50
```
- limit: Döndürülecek en fazla öğe sayısını belirtir.
  
  İpucu
  
  Hizmet reddi saldırılarını önlemeye yardımcı olmak için, döndürülen öğe sayısına üst sınır eklemeyi göz önünde bulundurun. Örneğin, hizmetiniz ayarlarsa max-limit=25ve bir istemci isterse limit=1000, API belgelerine bağlı olarak hizmetiniz 25 öğe veya HTTP BAD-REQUEST hatası döndürebilir.
- offset: Verilerin başlangıç dizinini belirtir.
Filtreleme, istemcilerin koşulları uygulayarak veri kümesini iyileştirmesine olanak tanır. API, istemcinin filtreyi URI'nin sorgu dizesinde geçirmesine izin verebilir:
```
GET /orders?minCost=100&status=shipped
```
- minCost: Minimum maliyeti 100 olan siparişleri filtreler.
- status: Belirli bir duruma sahip siparişleri filtreler.

Aşağıdaki en iyi yöntemleri göz önünde bulundurun:

Sıralama, istemcilerin verileri, sort gibi bir sort=price parametresi kullanarak sıralamasına olanak tanır.

Önemli

Sorgu dizesi parametreleri birçok önbellek uygulamasının önbelleğe alınan veriler için anahtar olarak kullandığı kaynak tanımlayıcısının bir parçasını oluşturduğundan, sıralama yaklaşımı önbelleğe alma üzerinde olumsuz bir etkiye sahip olabilir.
İstemci tanımlı projeksiyonlar için alan seçimi, istemcilerin gibi fieldsbir fields=id,name parametre kullanarak yalnızca ihtiyaç duydukları alanları belirtmesini sağlar. Örneğin, /orders?fields=ProductID,Quantity gibi virgülle ayrılmış bir alan listesini kabul eden bir sorgu dizesi parametresi kullanabilirsiniz.

İstemcinin bunlara erişmesine izin verildiğinden ve normalde API aracılığıyla kullanılamayacak alanları kullanıma sunmadığından emin olmak için API'nizin istenen alanları doğrulaması gerekir.

Kısmi yanıtları destekleme

Bazı kaynaklar dosyalar veya görüntüler gibi büyük ikili alanlar içerir. Güvenilir olmayan ve aralıklı bağlantıların neden olduğu sorunların üstesinden gelmek ve yanıt sürelerini iyileştirmek için büyük ikili kaynakların kısmi alınmasını desteklemeyi göz önünde bulundurun.

Kısmi yanıtları desteklemek için web API'sinin büyük kaynaklara yönelik GET isteklerine yönelik Accept-Ranges üst bilgisini desteklemesi gerekir. Bu üst bilgi GET işleminin kısmi istekleri desteklediğini gösterir. İstemci uygulaması, bayt aralığı olarak belirtilen bir kaynağın alt kümesini döndüren GET istekleri gönderebilir.

Ayrıca, bu kaynaklar için HTTP HEAD istekleri uygulamayı göz önünde bulundurun. HEAD isteği GET isteğine benzer, ancak yalnızca kaynağı açıklayan HTTP üst bilgilerini boş bir ileti gövdesiyle döndürür. İstemci uygulaması, kısmi GET istekleri kullanarak bir kaynağın getirilip getirilmeyeceğini belirlemek için bir HEAD isteği verebilir. Örneğin:

HEAD https://api.contoso.com/products/10?fields=productImage

Örnek bir yanıt iletisi aşağıda verilmişti:

HTTP/1.1 200 OK

Accept-Ranges: bytes
Content-Type: image/jpeg
Content-Length: 4580

content-length üst bilgisi kaynağın toplam boyutunu verir ve Accept-Ranges üst bilgisi ilgili GET işleminin kısmi sonuçları desteklediğini gösterir. İstemci uygulaması, görüntüyü daha küçük öbekler halinde almak için bu bilgileri kullanabilir. İlk istek, Aralık üst bilgisini kullanarak ilk 2.500 baytı getirir:

GET https://api.contoso.com/products/10?fields=productImage
Range: bytes=0-2499

Yanıt iletisi, HTTP durum kodu 206 döndürülerek bu yanıtın kısmi olduğunu gösterir. content-length üst bilgisi, kaynağın boyutunu değil ileti gövdesinde döndürülen gerçek bayt sayısını belirtir. İçerik Aralığı üst bilgisi, kaynağın hangi bölümünün döndürüldiğini gösterir (4580'den 0-2499 bayt):

HTTP/1.1 206 Partial Content

Accept-Ranges: bytes
Content-Type: image/jpeg
Content-Length: 2500
Content-Range: bytes 0-2499/4580

[...]

İstemci uygulamasından gelen sonraki bir talep, kaynağın geri kalanını geri alabilir.

HATEOAS'i uygulayın

REST kullanmanın birincil nedenlerinden biri, URI şeması hakkında önceden bilgi sahibi olmadan kaynak kümesinin tamamında gezinebilmektir. Her HTTP GET isteği, yanıta dahil edilen köprüler aracılığıyla doğrudan istenen nesneyle ilgili kaynakları bulmak için gerekli bilgileri döndürmelidir. İstek, bu kaynakların her birinde kullanılabilen işlemleri açıklayan bilgiler de verilmelidir. Bu ilke HATEOAS veya Uygulama Durumunun Motoru olarak Köprü Metni olarak bilinir. Sistem etkili bir şekilde sonlu bir durum makinesidir ve her isteğe verilen yanıt, bir durumdan diğerine geçmek için gereken bilgileri içerir. Başka hiçbir bilgi gerekli olmamalıdır.

Uyarı

HATEOAS ilkesinin nasıl modellendiğini tanımlayan genel amaçlı standartlar yoktur. Bu bölümdeki örneklerde olası, özel bir çözüm gösterilmektedir.

Örneğin, bir siparişle müşteri arasındaki ilişkiyi işlemek için siparişin gösterimi, siparişin müşterisi için kullanılabilir işlemleri tanımlayan bağlantılar içerebilir. Aşağıdaki kod bloğu olası bir gösterimdir:

{
  "orderID":3,
  "productID":2,
  "quantity":4,
  "orderValue":16.60,
  "links":[
    {
      "rel":"customer",
      "href":"https://api.contoso.com/customers/3",
      "action":"GET",
      "types":["text/xml","application/json"]
    },
    {
      "rel":"customer",
      "href":"https://api.contoso.com/customers/3",
      "action":"PUT",
      "types":["application/x-www-form-urlencoded"]
    },
    {
      "rel":"customer",
      "href":"https://api.contoso.com/customers/3",
      "action":"DELETE",
      "types":[]
    },
    {
      "rel":"self",
      "href":"https://api.contoso.com/orders/3",
      "action":"GET",
      "types":["text/xml","application/json"]
    },
    {
      "rel":"self",
      "href":"https://api.contoso.com/orders/3",
      "action":"PUT",
      "types":["application/x-www-form-urlencoded"]
    },
    {
      "rel":"self",
      "href":"https://api.contoso.com/orders/3",
      "action":"DELETE",
      "types":[]
    }]
}

Bu örnekte dizinin links bir bağlantı kümesi vardır. Her bağlantı, ilgili varlık üzerindeki bir işlemi temsil eder. Her bağlantının verileri ilişkiyi ("müşteri"), URI'yi (https://api.contoso.com/customers/3), HTTP yöntemini ve desteklenen MIME türlerini içerir. İstemci uygulamasının işlemi çağırmak için bu bilgilere ihtiyacı vardır.

Dizi, links alınan kaynak hakkında kendine referans veren bilgiler de içerir. Bu bağlantıların ilişkisi kendidir.

Döndürülen bağlantı kümesi, kaynağın durumuna bağlı olarak değişebilir. Köprü metin, uygulama durumunun motoru olduğu fikri bu senaryoyu açıklar.

Sürüm oluşturmayı uygula

Web API'leri statik olarak kalmaz. İş gereksinimleri değiştikçe yeni kaynak koleksiyonları eklenir. Yeni kaynaklar eklendikçe kaynaklar arasındaki ilişkiler değişebilir ve kaynaklardaki verilerin yapısı değiştirilebilir. Web API'sini yeni veya farklı gereksinimleri işleyecek şekilde güncelleştirmek basit bir işlemdir, ancak bu tür değişikliklerin web API'sini kullanan istemci uygulamaları üzerindeki etkilerini göz önünde bulundurmanız gerekir. Web API'sini tasarlayan ve uygulayan geliştirici bu API üzerinde tam denetime sahiptir, ancak iş ortağı kuruluşlar tarafından oluşturulan istemci uygulamaları üzerinde aynı düzeyde denetime sahip değildir. Yeni istemci uygulamalarının yeni özellikleri ve kaynakları kullanmasına izin verirken mevcut istemci uygulamalarını desteklemeye devam etmek önemlidir.

Sürüm oluşturma uygulayan bir web API'si, kullanıma sunabileceği özellikleri ve kaynakları gösterebilir ve istemci uygulaması bir özelliğin veya kaynağın belirli bir sürümüne yönlendirilen istekler gönderebilir. Aşağıdaki bölümlerde, her birinin kendi avantajları ve dezavantajları olan birkaç farklı yaklaşım açıklanmaktadır.

Sürüm oluşturma yok

Bu yaklaşım en basittir ve bazı iç API'ler için kullanılabilir. Önemli değişiklikler yeni kaynaklar veya yeni bağlantılar olarak gösterilebilir. Mevcut kaynaklara içerik eklemek, bu içeriği görmeyi beklemeyen istemci uygulamaları yoksaydığından dolayı, uyumsuzluk yaratan bir değişiklik olmayabilir.

Örneğin, URI'ye https://api.contoso.com/customers/3 yönelik bir istek, istemci uygulamasının beklediği , idve name alanlarını içeren addresstek bir müşterinin ayrıntılarını döndürmelidir:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","address":"1 Microsoft Way Redmond WA 98053"}

Uyarı

Kolaylık olması için, bu bölümde gösterilen örnek yanıtlar HATEOAS bağlantılarını içermez.

DateCreated Alan müşteri kaynağının şemasına eklenirse yanıt şöyle görünür:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","dateCreated":"2025-03-22T12:11:38.0376089Z","address":"1 Microsoft Way Redmond WA 98053"}

Mevcut istemci uygulamaları tanınmayan alanları yoksayabiliyorsa düzgün çalışmaya devam edebilir. Bu arada, yeni istemci uygulamaları bu yeni alanı işleyecek şekilde tasarlanabilir. Ancak, alan kaldırma veya yeniden adlandırma da dahil olmak üzere kaynakların şemasında daha büyük değişiklikler yapılabilir. Veya kaynaklar arasındaki ilişkiler değişebilir. Bu güncellemeler, mevcut istemci uygulamalarının düzgün çalışmasını engelleyen uyumsuz değişiklikler oluşturabilir. Bu senaryolarda aşağıdaki yaklaşımlardan birini göz önünde bulundurun:

URI sürümü oluşturma
Sorgu dizesi sürümleme
Başlık sürümlendirme
Medya türü sürüm oluşturma

URI sürümleme

Web API'sini her değiştirdiğinizde veya kaynak şemasını değiştirdiğinizde, her kaynağın URI'sine bir sürüm numarası eklersiniz. Daha önce var olan URI'ler, özgün şemalarına uygun kaynakları döndürerek normal şekilde çalışmaya devam etmelidir.

Örneğin, önceki örnekteki alan adresin address , , streetAddressve citygibi statezipCodeher bir kurucu bölümünü içeren alt alanlara yeniden yapılandırılmıştır. Kaynağın bu sürümü, gibi https://api.contoso.com/v2/customers/3bir sürüm numarası içeren bir URI aracılığıyla gösterilebilir:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","dateCreated":"2025-03-22T12:11:38.0376089Z","address":{"streetAddress":"1 Microsoft Way","city":"Redmond","state":"WA","zipCode":98053}}

Bu sürüm oluşturma mekanizması basittir ancak isteği uygun uç noktaya yönlendirmek için sunucuya bağlıdır. Bununla birlikte, web API'si çeşitli yinelemelerle olgunlaştıkça ve sunucunun birçok farklı sürümü desteklemesi gerektiğinden, bu durumu yönetmek zorlaşabilir. Purist açısından bakıldığında, istemci uygulamaları her durumda aynı verileri (müşteri 3) getirir, bu nedenle URI sürüme göre farklı olmamalıdır. Tüm bağlantıların URI'lerine sürüm numarasını içermesi gerektiğinden, bu şema HATEOAS uygulamasını da karmaşıklaştırır.

Sorgu dizesi sürümlendirme

Birden çok URI sağlamak yerine, HTTP isteğine eklenen sorgu dizesi içinde bir parametre kullanarak kaynağın sürümünü belirtebilirsiniz; örneğin https://api.contoso.com/customers/3?version=2. Eski istemci uygulamaları bunu atlarsa sürüm parametresi varsayılan olarak 1 gibi anlamlı bir değere ayarlanmalıdır.

Bu yaklaşım, aynı kaynağın her zaman aynı URI'den alınması semantik avantajına sahiptir. Ancak, bu yöntem sorgu dizesini ayrıştırma ve uygun HTTP yanıtını geri gönderme isteğini işleyen koda bağlıdır. Bu yaklaşım, HATEOAS uygulamasını URI sürüm oluşturma mekanizmasıyla aynı şekilde de karmaşıklaştırır.

Uyarı

Bazı eski web tarayıcıları ve web proxy'leri, URI'de sorgu dizesi içeren istekler için yanıtları önbelleğe almaz. Önbelleğe alınmamış yanıtlar, web API kullanan ve eski bir web tarayıcıda çalışan web uygulamalarının performansını düşürebilir.

Üst bilgi sürümlendirme

Sürüm numarasını sorgu dizesi parametresi olarak eklemek yerine, kaynağın sürümünü gösteren özel bir üst bilgi uygulayabilirsiniz. Bu yaklaşım, istemci uygulamasının tüm isteklere uygun üst bilgiyi eklemesini gerektirir. Ancak, istemci isteğini işleyen kod, sürüm üst bilgisi atlanırsa sürüm 1 gibi bir varsayılan değer kullanabilir.

Aşağıdaki örneklerde Custom-Header adlı özel bir üst bilgi kullanılır. Bu üst bilginin değeri web API'sinin sürümünü gösterir.

Sürüm 1:

GET https://api.contoso.com/customers/3
Custom-Header: api-version=1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","address":"1 Microsoft Way Redmond WA 98053"}

Sürüm 2:

GET https://api.contoso.com/customers/3
Custom-Header: api-version=2

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","dateCreated":"2025-03-22T12:11:38.0376089Z","address":{"streetAddress":"1 Microsoft Way","city":"Redmond","state":"WA","zipCode":98053}}

URI sürüm oluşturma ve sorgu dizesi sürüm oluşturma işlemlerine benzer şekilde, HATEOAS'ı uygulamak için tüm bağlantılara uygun özel üst bilgiyi eklemeniz gerekir.

Medya türü sürümleme

İstemci uygulaması bir web sunucusuna HTTP GET isteği gönderdiğinde, işleyebileceği içeriğin biçimini belirtmek için Accept üst bilgisini kullanmalıdır. Accept üst bilgisinin amacı genellikle istemci uygulamasının yanıtın gövdesinin XML mi, JSON mı yoksa istemcinin ayrıştırabileceği başka bir ortak biçim mi olması gerektiğini belirtmesine izin vermektir. Ancak, istemci uygulamasının kaynağın hangi sürümünü beklediğini belirtmesine olanak tanıyan bilgiler içeren özel medya türleri tanımlamak mümkündür.

Aşağıdaki örnekte değeri application/vnd.contoso.v1+json ile bir Accept üst bilgisi belirten bir istek gösterilmektedir. vnd.contoso.v1 öğesi, web sunucusuna kaynağın 1. sürümünü döndürmesi gerektiğini belirtir. json öğesi, yanıt gövdesinin biçiminin JSON olması gerektiğini belirtir:

GET https://api.contoso.com/customers/3
Accept: application/vnd.contoso.v1+json

İsteği işleyen kod Accept üst bilgisini işlemek ve mümkün olduğunca kabul etmekle sorumludur. İstemci uygulaması, Web sunucusunun yanıt gövdesi için en uygun biçimi seçmesini sağlayan Accept üst bilgisinde birden çok biçim belirtebilir. Web sunucusu, content-Type üst bilgisini kullanarak yanıt gövdesindeki verilerin biçimini onaylar:

HTTP/1.1 200 OK
Content-Type: application/vnd.contoso.v1+json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","address":"1 Microsoft Way Redmond WA 98053"}

Kabul Et üst bilgisi bilinen medya türlerini belirtmezse, web sunucusu bir HTTP 406 (Kabul Edilemez) yanıt iletisi oluşturabilir veya varsayılan medya türüne sahip bir ileti döndürebilir.

Bu sürüm oluşturma mekanizması, kaynak bağlantılarındaki ilgili verilerin MIME türünü içerebilen HATEOAS için basittir ve uygundur.

Uyarı

Bir sürüm oluşturma stratejisi seçtiğinizde, özellikle web sunucusu önbelleğe alma ile ilgili etkiler. Aynı URI veya sorgu dizesi bileşimi her seferinde aynı verilere başvurduğundan URI sürüm oluşturma ve sorgu dizesi sürüm oluşturma şemaları önbellek kullanımına uygundur.

Üst bilgi sürüm oluşturma ve medya türü sürüm oluşturma mekanizmaları genellikle özel üst bilgideki veya Accept üst bilgisindeki değerleri incelemek için daha fazla mantık gerektirir. Büyük ölçekli bir ortamda, bir web API'sinin farklı sürümlerini kullanan birçok istemci, sunucu tarafı önbelleğinde önemli miktarda yinelenen veriyle sonuçlanabilir. İstemci uygulaması, önbelleğe alma yapan bir vekil sunucu aracılığıyla web sunucusuyla iletişim kurarsa ve sadece istenen verilerin bir kopyası önbelleğinde yoksa isteği web sunucusuna iletirse, bu sorun ciddi hale gelebilir.

Çok kullanıcılı web API'leri

Çok kiracılı bir web API çözümü, kendi kullanıcı gruplarına sahip farklı kuruluşlar gibi birden çok kiracı tarafından paylaşılır.

Çok kiracılılık, tek bir web API'sinde birden çok kiracıda kaynaklara nasıl erişilebileceği ve bulunacağından web API'sinin tasarımını önemli ölçüde etkiler. Gelecekte yalıtım, ölçeklenebilirlik veya kiracıya özgü özelleştirmeler uygulamak için yeniden düzenleme ihtiyacını önlemeye yardımcı olmak adına, çok kiracılılık düşünülerek bir API tasarla.

İyi tasarlanmış bir API, isteklerde kiracıların alt etki alanları, yollar, üst bilgiler veya belirteçler aracılığıyla nasıl tanımlandığını açıkça ortaya koymalıdır. Bu yapı, sistemdeki tüm kullanıcılar için tutarlı ancak esnek bir deneyim sağlar. Daha fazla bilgi için bkz. Çok kiracılı bir çözümde istekleri kiracılarla eşleştirme.

Çok kiracılılık uç nokta yapısını, istek işlemeyi, kimlik doğrulamayı ve yetkilendirmeyi etkiler. Bu yaklaşım API ağ geçitlerinin, yük dengeleyicilerin ve arka uç hizmetlerinin istekleri yönlendirme ve işleme şeklini de etkiler. Aşağıdaki stratejiler, web API'sinde çok kiracılılık elde etmenin yaygın yollarıdır.

Alt alan adı veya etki alanı tabanlı yalıtım kullanma (DNS düzeyinde bölümlendirme)

Bu yaklaşım, kiracıya özgü etki alanlarını kullanarak istekleri yönlendirir. Joker etki alanları esneklik ve basitlik için alt etki alanlarını kullanır. Kiracıların kendi etki alanlarını kullanmasına olanak tanıyan özel etki alanları daha fazla denetim sağlar ve belirli gereksinimleri karşılayacak şekilde uyarlanabilir. Her iki yöntem de trafiği uygun altyapıya yönlendirmek için, A ve CNAME kayıtları da dahil olmak üzere uygun DNS yapılandırmasına dayanır. Genel etki alanları yapılandırmayı basitleştirir, ancak özel etki alanları daha iyi markalanmış bir deneyim sunar.

URL yeniden yönlendirmesi gibi sorunlardan kaçınmak ve iç URL'lerin açığa çıkmasını önlemek için ters ara sunucu ile arka uç hizmetleri arasındaki ana bilgisayar adını koruyun. Bu yöntem, kiracıya özgü trafiğin doğru yönlendirilmesini sağlar ve iç altyapının korunmasına yardımcı olur. DNS çözümlemesi, veri yerleşimi elde etmek ve mevzuat uyumluluğunu sağlamak için çok önemlidir.

GET https://adventureworks.api.contoso.com/orders/3

Kiracıya özgü HTTP üst bilgilerini aktarma

Kiracı bilgileri, X-Tenant-ID veya X-Organization-ID gibi özel HTTP üst bilgileriyle ya da Host veya X-Forwarded-Host gibi konak tabanlı üst bilgilerle geçirilebilir veya JSON Web Belirteci (JWT) taleplerinden ayıklanabilir. Seçim, API ağ geçidinizin veya ters vekil sunucunuzun yönlendirme yeteneklerine bağlıdır ve üst bilgi tabanlı çözümler her isteği incelemek için Katman 7 (L7) ağ geçidi gerektirir. Bu gereksinim, trafik ölçeklendirildiğinde işlem maliyetlerini artıran işleme ek yükü ekler. Ancak, üst bilgi tabanlı yalıtım önemli avantajlar sağlar. Çok kiracılı API'ler arasında güvenlik yönetimini basitleştiren merkezi kimlik doğrulamasını etkinleştirir. KIRACı bağlamı, SDK'lar veya API istemcileri kullanılarak çalışma zamanında dinamik olarak yönetilir ve bu da istemci tarafı yapılandırma karmaşıklığını azaltır. Ayrıca, kiracı bağlamının üst bilgilerde tutulması, URI'deki kiracıya özgü verilerden kaçınarak daha temiz ve daha fazla RESTful API tasarımına neden olur.

Özellikle önbellek katmanları yalnızca URI tabanlı anahtarlara bağımlı olduğunda ve üst bilgileri hesaba katmadığında, üst bilgi tabanlı yönlendirme için dikkat edilmesi gereken önemli noktalardan biri, önbelleğe almayı karmaşık hale getiren bir özelliktir. Çoğu önbelleğe alma mekanizması URI aramaları için iyileştirildiğinden, üst bilgileri kullanmak parçalanmış önbellek girişlerine yol açabilir. Parçalanmış girişler önbellek isabetlerini azaltır ve arka uç yükünü artırır. Daha da önemlisi, önbelleğe alma katmanı yanıtları başlıklara göre ayırmazsa, bir kiracıya yönelik önbelleğe alınmış veriyi başka bir kiracıya iletebilir ve veri sızıntısı riski ortaya çıkarabilir.

GET https://api.contoso.com/orders/3
X-Tenant-ID: adventureworks

veya

GET https://api.contoso.com/orders/3
Host: adventureworks

veya

GET https://api.contoso.com/orders/3
Authorization: Bearer <JWT-token including a tenant-id: adventureworks claim>

Kiracıya özgü bilgileri URI yolundan geçirin

Bu yaklaşım, kaynak hiyerarşisine kiracı tanımlayıcılarını ekler ve yol segmentine göre uygun kiracıyı belirlemek için API ağ geçidine veya ters proxyye dayanır. Yol tabanlı yalıtım etkilidir, ancak web API'sinin RESTful tasarımını tehlikeye atarak daha karmaşık yönlendirme mantığı sağlar. Genellikle URI yolunu ayrıştırmak ve kurallı hale getirmek için desen eşleştirme veya normal ifadeler gerektirir.

Buna karşılık, başlık tabanlı yalıtım kiracı bilgilerini HTTP başlıkları aracılığıyla anahtar-değer çiftleri olarak iletir. Her iki yaklaşım da operasyonel maliyetleri düşürmek ve büyük ölçekli, çok kiracılı web API'lerinde performansı artırmak için verimli altyapı paylaşımı sağlar.

GET https://api.contoso.com/tenants/adventureworks/orders/3

API'lerde dağıtılmış izleme ve izleme bağlamını etkinleştirme

Dağıtılmış sistemler ve mikro hizmet mimarileri standart hale geldikçe modern mimarilerin karmaşıklığı artar. API isteklerinde izleme bağlamını yaymak için , Correlation-IDveya X-Request-IDgibi X-Trace-IDüst bilgileri kullanmak, uçtan uca görünürlük elde etmek için en iyi yöntemdir. Bu yaklaşım, istemciden arka uç hizmetlerine akan isteklerin sorunsuz bir şekilde izlenmesini sağlar. Hataların hızlı bir şekilde tanımlanmasını kolaylaştırır, gecikme süresini izler ve api bağımlılıklarını hizmetler arasında eşler.

İzleme ve bağlam bilgilerinin eklenmesini destekleyen API'ler gözlemlenebilirlik düzeyini ve hata ayıklama özelliklerini geliştirir. Dağıtılmış izlemeyi etkinleştiren bu API'ler, sistem davranışının daha ayrıntılı bir şekilde anlaşılmasını sağlar ve karmaşık, çok hizmetli ortamlardaki sorunları izlemeyi, tanılamayı ve çözmeyi kolaylaştırır.

GET https://api.contoso.com/orders/3
Correlation-ID: 0f8fad5b-d9cb-469f-a165-70867728950e

HTTP/1.1 200 OK
...
Correlation-ID: 0f8fad5b-d9cb-469f-a165-70867728950e

{...}

Web API olgunluk modeli

2008 yılında Leonard Richardson, web API'leri için Richardson Olgunluk Modeli (RMM) olarak bilinen şeyi önerdi. RMM, web API'leri için dört olgunluk düzeyi tanımlar ve web hizmetlerini tasarlamaya yönelik mimari bir yaklaşım olarak REST ilkelerini temel alır. RMM'de, olgunluk düzeyi arttıkça API daha FAZLA RESTful olur ve REST ilkelerini daha yakından izler.

Düzeyler şunlardır:

Düzey 0: Bir URI tanımlayın ve tüm işlemler bu URI'ye yönelik POST istekleridir. Basit Nesne Erişim Protokolü web hizmetleri genellikle bu düzeydedir.
Düzey 1: Tek tek kaynaklar için ayrı URI'ler oluşturun. Bu düzey henüz tamamen RESTful değildir, ancak RESTful tasarımına doğru bir başlangıç yapmaktadır.
Düzey 2: Kaynaklarda işlemleri tanımlamak için HTTP yöntemlerini kullanın. Uygulamada, yayımlanan birçok web API'si yaklaşık olarak bu düzeyle hizalanır.
Düzey 3: Hipermedya (HATEOAS) kullanın. Fielding'in tanımına göre bu düzey gerçekten bir RESTful API'dir.

OpenAPI Girişimi

OpenAPI Girişimi, satıcılar arasında REST API açıklamalarını standart hale getirmek için bir sektör konsorsiyumu tarafından oluşturulmuştur. Standartlaştırma belirtimi, OpenAPI Girişimi altına getirilmeden önce Swagger olarak adlandırıldı ve OpenAPI Belirtimi (OAS) olarak yeniden adlandırıldı.

RESTful web API'leriniz için OpenAPI'yi benimsemek isteyebilirsiniz. Aşağıdaki noktaları göz önünde bulundurun:

OAS, REST API tasarımı için belirli ilkeler üzerine kurulu bir dizi kılavuz ile birlikte gelir. Yönergeler birlikte çalışabilirlik açısından avantajlıdır ancak tasarımınızın belirtimlere uygun olduğundan emin olmanız gerekir.
OpenAPI, uygulama öncelikli yaklaşım yerine sözleşme öncelikli bir yaklaşımı yükseltir. Sözleşme öncelikli, önce API sözleşmesini (arabirim) tasarladığınız ve ardından sözleşmeyi uygulayan kodu yazabileceğiniz anlamına gelir.
Swagger (OpenAPI) gibi araçlar API sözleşmelerinden istemci kitaplıkları veya belgeler oluşturabilir. Örnek için Swagger/OpenAPI ile ASP.NET Core web API belgelerini inceleyin.

Sonraki adımlar

Azure'da REST API'leri tasarlamaya yönelik ayrıntılı önerilere bakın.
Web API'sini tasarlayıp uygularken göz önünde bulundurmanız gereken öğelerin denetim listesine bakın.
Azure'da hizmet olarak yazılım ve çok kiracılı çözüm mimarileri oluşturun.

Aracılığıyla paylaş

RESTful web API'si tasarımı için en iyi yöntemler

RESTful web API'si tasarım kavramları

RESTful web API kaynak URI'lerini tanımlama

Kaynak URI adlandırma kuralları

RESTful web API yöntemlerini tanımlama

HTTP isteği yöntemleri

GET istekleri

POST istekleri

PUT isteği

PATCH istekleri

DELETE istekleri

Kaynak MIME türleri

Zaman uyumsuz yöntemler uygulama

Veri sayfalandırmayı ve filtrelemeyi uygulamak

Kısmi yanıtları destekleme

HATEOAS'i uygulayın

Sürüm oluşturmayı uygula

Sürüm oluşturma yok

URI sürümleme

Sorgu dizesi sürümlendirme

Üst bilgi sürümlendirme

Medya türü sürümleme

Çok kullanıcılı web API'leri

Alt alan adı veya etki alanı tabanlı yalıtım kullanma (DNS düzeyinde bölümlendirme)

Kiracıya özgü HTTP üst bilgilerini aktarma

Kiracıya özgü bilgileri URI yolundan geçirin

API'lerde dağıtılmış izleme ve izleme bağlamını etkinleştirme

Web API olgunluk modeli

OpenAPI Girişimi

Sonraki adımlar

Geri Bildirim

Ek kaynaklar