RESTful web API'sini uygulama için en iyi yöntemler

Bu makalede RESTful web API'sini uygulamaya, dağıtmaya ve çalıştırmaya yönelik en iyi yöntemler açıklanmaktadır. İstek işleme, performans, güvenilirlik, yayımlama ve izlemeye odaklanır. Kaynak modelleme ve API tasarımı hakkında rehberlik için bkz. Web API tasarımı.

Mimari kılavuz, uygulama dilleri ve çerçeveleri arasında geçerlidir. C# örnekleri ASP.NET Core denetleyicilerini gösterir.

İstekleri işleme

İstekleri işlemek üzere kod uygularken aşağıdaki noktaları göz önünde bulundurun.

HTTP yöntemi semantiğini koruyun ve idempotency uygulayın

Kaynak verilerini döndürmek için GET ve gövde olmadan yanıt üst bilgilerini döndürmek için HEAD kullanın. Kaynakları oluşturmak, güncelleştirmek veya silmek için herhangi bir yöntem kullanmayın.

GET, HEAD, PUT ve DELETE idempotent olmalıdır, bu nedenle aynı isteğin yinelenmesi, isteğin bir kez gerçekleştirilmesiyle aynı etkiye sahiptir. Örneğin, DELETE kaynak durumunu değiştirir, ancak bunu tekrarlamak ek kaynakları silmez. İlk DELETE isteği 204 (İçerik Yok) döndürebilirken, sonraki bir istek 404 (Bulunamadı) döndürür.

POST ve PATCH doğası gereği idempotent değildir. Bir özelliği bir değere ayarlayan PATCH işlemi idempotent olabilir, ancak sayacı artıran bir işlem değildir. Durum değiştiren işlemlerin hangilerini güvenli bir şekilde yeniden deneyebileceğini belgeleyin. Doğal olarak idempotent olmayan işlemler için yeniden denemeleri destekliyorsanız, hizmetin yinelenen etkileri nasıl önlediğini uygulayın ve belgeleyin. Yöntem semantiği için bkz. HTTP isteği yöntemleri.

Not

Uygulama kılavuzu için bkz. Idempotent Consumer pattern. Uygulamada, ilk olarak bir işlemin doğal olarak idempotent olup olmadığını belirleyin. Değilse, işlenen ileti kimliklerini izleyerek ve yinelenenleri proaktif veya reaktif olarak işleyerek yapay bir idempotensi uygulayın.

İstek verilerini doğrulama ve alan erişimini denetleme

Yalnızca API sözleşmesindeki alanları kullanıma sunan istek ve yanıt modellerini tanımlayın. İstek gövdelerini doğrudan veritabanı varlıklarına bağlamak veya depolanan her özelliği döndürmek yerine bu modelleri depolanan verilerle eşleyin. Arayanların ek alanlar göndererek korumalı özellikleri değiştirmesini önleyin ve okumaya yetkili olmadıkları özellikleri hariç tutun. Veri aktarım nesneleri (DTO'lar) bu sınırı uygulamanın bir yoludur. Daha fazla bilgi için bkz. ASP.NET Core'da fazla göndermeyi önleme.

Değişiklikleri kaydetmeden önce gerekli alanları, türleri, aralıkları ve iş kurallarını doğrulayın. Alan seçimini destekliyorsanız, yanıtı oluşturmadan önce istenen alanları izin verilenler listesine ve çağıranın izinlerine göre doğrulayın. Filtrelemeye ve sıralamaya da belgelenmiş sınırlar uygulayın. İlgili sözleşme seçimleri için bkz. Sayfalandırma ve filtrelemeyi uygulama.

Kaynak oluşturan POST eylemlerinin yan etkilerini sınırlama

POST isteği bir kaynak oluşturduğunda, etkilerini bu kaynak ve doğrudan ilişkili kaynaklarla sınırlayın. Örneğin, bir sipariş oluşturma işlemi envanteri güncelleştirebilir ve faturalama bilgileri oluşturabilir. İlişkisiz bilgileri değiştirmemelidir.

Sık iletişim kuran POST, PUT ve DELETE işlemlerini uygulamaktan kaçının

API'nizi fazla iletişimli işlemlere göre tasarlamaktan kaçının. Her istek protokol, ağ ve işlem yüküyle birlikte gelir. Örneğin, daha büyük bir toplu iş isteği yerine 100 daha küçük istek çalıştırmak, istemcide, ağda ve kaynak sunucusunda ek yüke neden olur. Toplu işlemler gerektiren iş yükleri için, birçok tek tek istek yerine sınırlandırılmış toplu istekleri göz önünde bulundurun.

  • Bir koleksiyona get isteği aynı anda birden çok kaynak alabilir.
  • POST isteği birden çok yeni kaynağın ayrıntılarını içerebilir ve bunların tümünü aynı koleksiyona ekleyebilir.
  • PUT isteği, bir koleksiyondaki tüm kaynak kümesinin yerini alabilir.
  • DELETE isteği koleksiyonun tamamını kaldırabilir.

Maksimum toplu iş boyutlarını, payload boyutlarını, yürütme sürelerini ve eşzamanlı yürütmeyi tanımlayın. Toplu işlemin atomik olup olmadığını veya kısmen başarılı olup olmayacağını belirtin ve her işlem için bir sonuç döndürün. Toplu iş içindeki her işlemi yetkilendirin ve doğrulayın.

OData kullanıyorsanız, toplu istekleri uygulamak için ASP.NET Core OData kullanabilirsiniz. Daha fazla bilgi için bkz. ASP.NET Core OData genel bakış.

Yanıt gönderirken HTTP belirtimini takip edin

İstemcilerin yanıtı yorumlayabilmesi ve işleyebilmesi için uygun HTTP durum kodunu, üst bilgileri ve gövde biçimini döndürün.

Örneğin, eşzamanlı olarak kaynak oluşturan bir POST işlemi 201 (Oluşturuldu) döndürmelidir ve Location yanıt üst bilgisinde kaynağı tanımlamalıdır. Daha sonra işleme için çalışmayı kabul eden bir işlem 202 (Kabul Edildi) döndürebilir, ancak bu yanıt çalışmanın başarılı olduğunu göstermez. 204 (İçerik Yok) veya 304 (Değiştirilmedi) ile birlikte yanıt gövdesi eklemeyin. Daha fazla bilgi için bkz. HTTP isteği yöntemleri.

İçerik anlaşmasını destekler

Yanıt gövdesi JSON veya XML gibi farklı biçimlerde veriler içerebilir. İstemciler desteklenen medya türlerini belirtmek için Accept istek üst bilgisini kullanabilir. Örneğin, görüntü isteyen bir istemci image/jpeg, image/gif, image/png belirtebilir. Desteklenen bir gösterim döndürün ve medya türünü Content-Type yanıt üst bilgisinde belirtin.

İstemci Accept header belirtmezse, belgelenmiş varsayılan biçimi kullanın. ASP.NET Core denetleyicileri varsayılan olarak JSON biçimlendiricileri kullanır. API istenen gösterimi oluşturamayınca ne olacağını tanımlayın. Örneğin, API'yi desteklenmeyen bir biçimi sessizce döndürmek yerine 406 (Kabul Edilemez) döndürecek şekilde yapılandırın. Daha fazla bilgi için bkz. ASP.NET Core Web API'sinde yanıt verilerini biçimlendirme.

Bir gövdeye sahip istekler için, isteğin Content-Type öğesini denetleyin ve yalnızca işlemin desteklediği biçimleri kabul edin. Desteklenmeyen bir biçim için 415 (Desteklenmeyen Medya Türü) döndürür. Bu denetim, Accept aracılığıyla yapılan yanıt uzlaşmasından ayrıdır. ASP.NET Core'da, giriş biçimlendiricilerini yapılandırın ve bir işlemin istek biçimlerini kısıtlamanız gerektiğinde [Consumes] öğesini kullanın. Daha fazla bilgi için bkz. ASP.NET Core ile web API'leri oluşturma.

Seçili API sürümlendirme stratejisini uygulayın

Tasarım sırasında seçtiğiniz sürüm oluşturma stratejisini uygulama ve ağ geçidinde tutarlı bir şekilde uygulayın. İstekleri seçilen sürüm için işleyiciye ve yanıt şemasına yönlendirin. Mevcut bir çağıranın alacağı sözleşmeyi sessizce değiştirmek yerine atlanan, hatalı biçimlendirilmiş ve desteklenmeyen sürüm tanımlayıcıları için davranışı tanımlayın.

Desteklenen sürümlerin istek ve yanıt sözleşmelerini koruyun. Geriye dönük uyumluluğu bozan bir değişiklik yaptığınızda yeni bir sürüm sağlayın ve desteklenen önceki sürümleri kullanılabilir durumda tutun. Yeni eklenen isteğe bağlı alanları atlayan eski arayanlardan gelen istekleri işleyin. Daha fazla bilgi için bkz. API sürümlendirme ve uyumluluk.

Oluşturulan kaynak bağlantılarını ve önbelleğe alınan gösterimleri seçili sürümle tutarlı tutun. Üst bilgi tabanlı sürüm oluşturma için, önbelleklerin yalnızca URI'ye bağlı kalmak yerine farklı sürümler için istekleri ayırt ettiğinden emin olun.

Kiracı bağlamını çözümleyin ve yetkilendirin

Çok kiracılı bir API için, her istek için kiracıyı belirleyin ve kimliği doğrulanmış çağıranın bu kiracıya erişebildiğini doğrulayın. Yollardaki, ana bilgisayar adlarındaki ve üst bilgilerdeki tenant tanımlayıcılarını yalnızca yönlendirme girişleri olarak değerlendirin. Daha fazla bilgi için bkz. Çok kiracılı bir çözümde istekleri kiracılarla eşleştirme.

Verileri sorgularken veya güncelleştirirken ve işi arka plan işlemcilerine teslim ederken yetkili kiracı bağlamını tutarlı bir şekilde kullanın. Uygulama veya ağ geçidi önbellekleri kiracıya özgü verileri depolarsa, önbellek anahtarına kiracı tanımlayıcısını ekleyin. Ağ geçidine özgü yönergeler için bkz. Çok kiracılılığı destekleyen API Management özellikleri.

Uygulama Durumunun Motoru Olarak Köprü Metni (HATEOAS), istemcilerin kaynakları keşfetmesine ve bunlar arasında gezinmesine yardımcı olmak için bağlantıları kullanır. Örneğin, müşteri ayrıntılarını içeren bir yanıt, bu müşterinin siparişlerinin bağlantılarını içerebilir. Get, POST, PUT ve DELETE gibi bağlı her kaynağın desteklediği işlemleri açıklayın ve ilgili URI'leri sağlayın. Daha fazla bilgi için bkz. API tasarımı.

Aşağıdaki örnek, uygulama tanımlı bağlantı gösterimini kullanır. İstemcilerin özel bağlantı alanlarını yorumlayabildiğini varsaymak yerine özel bağlantı alanlarının uzlaşımlarını belgele. Bir müşteri için GET isteği, bu müşterinin siparişlerinin bağlantılarını döndürür:

GET https://api.contoso.com/customers/2 HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
...
Content-Type: application/json; charset=utf-8
...
Content-Length: ...
{"customerId": 2,"customerName": "Bert","links": [
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "GET",
     "types": ["text/xml","application/json"]},
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "PUT",
     "types": ["application/x-www-form-urlencoded"]},
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "DELETE",
     "types": []},
    {"rel": "orders",
     "href": "https://api.contoso.com/customers/2/orders",
     "action": "GET",
     "types": ["text/xml","application/json"]},
    {"rel": "orders",
     "href": "https://api.contoso.com/customers/2/orders",
     "action": "POST",
     "types": ["application/x-www-form-urlencoded"]}
]}

Aşağıdaki Customer kayıt müşteri verilerini temsil eder. Links özelliği HATEOAS bağlantılarını içerir.

public sealed record Customer(
    int CustomerId,
    string CustomerName,
    IReadOnlyList<Link> Links);

public sealed record Link(
    string Rel,
    string Href,
    string Action,
    IReadOnlyList<string> Types);

GET işlemi, müşteri verilerini depolama alanından alır, Customer kaydını bağlantılarıyla birlikte oluşturur ve bir JSON yanıtı döndürür. Her bağlantı aşağıdaki alanları içerir:

  • Döndürülen kaynak ile bağlı kaynak arasındaki ilişki (Rel). Bu örnekte self müşteriyi ifade eder ve orders müşterinin sipariş koleksiyonunu ifade eder.
  • Bağlantı tarafından açıklanan nesnenin URI biçimindeki hiper bağlantısı (Href).
  • URI'ye gönderilebilen HTTP isteğinin (Action) türü.
  • İstek türüne bağlı olarak, HTTP isteğinde belirtilmesi gereken veya yanıtta döndürülebilecek her türlü verinin biçimi (Types).

Örnek HTTP yanıtında gösterilen HATEOAS bağlantıları, bir istemci uygulamanın aşağıdaki işlemleri gerçekleştirebileceğini ifade eder:

  • https://api.contoso.com/customers/2 adresine müşteri ayrıntılarını XML veya JSON olarak almak için bir HTTP GET isteği.
  • https://api.contoso.com/customers/2 öğesine müşteri ayrıntılarını değiştirmek için bir HTTP PUT isteği. İstek gövdesi şu biçimi kullanır: application/x-www-form-urlencoded.
  • Müşteri kaydını silmek için https://api.contoso.com/customers/2 adresine bir HTTP DELETE isteği gönderilir. Bu işlem istek gövdesi gerektirmez ve yanıt gövdesi döndürmez.
  • Müşterinin siparişlerini XML veya JSON olarak almak için https://api.contoso.com/customers/2/orders adresine yapılan bir HTTP GET isteği.
  • Müşteri için sipariş oluşturmak üzere https://api.contoso.com/customers/2/orders adresine bir HTTP POST isteği. İstek gövdesi şu biçimi kullanır: application/x-www-form-urlencoded.

Özel Durumların Yönetimi

Bir işlem yakalanmayan bir özel durum fırlatırsa aşağıdaki yönergeleri göz önünde bulundurun.

Özel durumları yakalama ve istemcilere anlamlı bir yanıt döndürme

Özel durumları tutarlı bir şekilde işleyip istemcilerle paylaşılması güvenli olan anlamlı bir hata yanıtı döndürün. Üretim yanıtlarında özel durum nesneleri, yığın izlemeleri veya iç uygulama ayrıntıları döndürmeyin. Her durum için 500 durum kodunu döndürmek yerine hatayı yansıtan bir HTTP durum kodu döndürün. Örneğin, bir kullanıcı isteği bir kısıtlamayı ihlal eden bir veritabanı güncelleştirmesine neden oluyorsa (bekleyen siparişleri olan bir müşteriyi silmeye çalışmak gibi), 409 (Çakışma) ve güvenli bir açıklama döndürün. Hatalı biçimlendirilmiş giriş veya istek doğrulama hataları için 400 (Hatalı İstek) döndür, beklenmeyen sunucu hataları için değil. HTTP durum tanımları için bkz. Durum Kodları. Uygulama yönergeleri için ASP.NET Core'da hataları işleme bölümüne bakın.

Aşağıdaki controller beklenen alan sonuçlarını HTTP yanıtlarıyla eşler. Depo/repository işlemi, silme işleminin bir parçası olarak yetkilendirmeyi ve bekleyen siparişleri denetler. Beklenmeyen hatalar, her eylemde sessizce yakalanmak yerine merkezi istisna işlemeye yayılır.

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Authorize]
[Route("customers")]
public sealed class CustomersController(ICustomerRepository repository) : ControllerBase
{
    [HttpDelete("{id:int}")]
    public async Task<IActionResult> DeleteCustomer(int id, CancellationToken cancellationToken)
    {
        var outcome = await repository.DeleteAuthorizedAsync(id, User, cancellationToken);

        return outcome switch
        {
            DeleteOutcome.Deleted => NoContent(),
            DeleteOutcome.NotFound => NotFound(),
            DeleteOutcome.HasOutstandingOrders => Conflict(new ProblemDetails
            {
                Status = StatusCodes.Status409Conflict,
                Title = "The customer has outstanding orders."
            }),
            _ => throw new InvalidOperationException("Unknown deletion outcome.")
        };
    }
}

public enum DeleteOutcome
{
    Deleted,
    NotFound,
    HasOutstandingOrders
}

Önemli

API'nize yetkisiz erişim elde etmeye çalışan bir saldırgan için yararlı olabilecek bilgileri eklemeyin.

Barındırma katmanı, API'ye ulaşmadan önce istekleri reddedebilir. Örneğin, kimlik doğrulama hataları 401 (Yetkisiz) yanıtlara neden olabilir. Kimlik doğrulamasından sonra, çağıranın istenen kaynağa erişme yetkisine sahip olduğunu doğrulayın. Yetkilendirme başarısız olduğunda 403 (Yasak) değerini döndürür.

Özel durumları tutarlı bir şekilde ele alın ve hata bilgilerini kaydedin.

Özel durumları tutarlı bir şekilde işlemek için web API'sinin tamamında genel bir hata işleme stratejisi uygulamayı göz önünde bulundurun. Tanılama bilgilerini sunucuda günlüğe kaydedip gizli dizileri, erişim belirteçlerini ve hassas kişisel verileri hariç tutun. Günlük girdileri yazmadan önce hassas değerleri gizleyin ve günlüklere erişimi yalnızca yetkili kullanıcılarla sınırlayın. Daha fazla bilgi için bkz. İzleme ve tehdit algılama için mimari stratejileri.

ASP.NET Core'da, tutarlı bir hata sözleşmesi için özel durum işleme ara yazılımını ve Sorun Ayrıntıları yanıtlarını kullanın. Tanılama ayrıntılarını atlayarak üretim yanıtlarını yapılandırın ve destek ekiplerinin ilgili günlükleri bulmak için kullanabileceği bir bağıntı tanımlayıcısı ekleyin. Daha fazla bilgi için, bkz. ASP.NET Core’da hataları işleme.

İstemci tarafı hataları ile sunucu tarafı hatalarını birbirinden ayırt etme

İstemci hataları için HTTP 4xx durum kodlarını ve sunucu hataları için HTTP 5xx durum kodlarını kullanın. Hata yanıtlarında bu ayrımı koruyun.

İstemci tarafı veri erişimini en iyi duruma getirme

Sık istekler ve büyük yanıtlar ağı bir darboğaz hâline getirebilir. Kaynak alma ve güncelleştirmeleri uygularken gereksiz aktarımları azaltın.

İstemci tarafı önbelleğe alma desteği

İstemcilerin ve ara sunucuların bir yanıtı depolayıp depolamayacağını ve ne kadar süre güncel kalacağını belirtmek için Cache-Control yanıt üst bilgisini kullanın.

Aşağıdaki örnekte bir HTTP GET isteği ve Cache-Control üst bilgisi içeren ilgili yanıt gösterilmektedir:

GET https://api.contoso.com/orders/2 HTTP/1.1

HTTP/1.1 200 OK
...
Cache-Control: max-age=600, private
Content-Type: application/json
Content-Length: 59

{"orderId":2,"productId":4,"quantity":2,"orderValue":10.00}

Bu örnekte yanıt 600 saniye boyunca güncel kalır. private yönergesi, tarayıcı önbelleği gibi özel bir önbellekte depolamaya izin verir, ancak paylaşılan bir önbellekte depolamayı yasaklar. Arayanlar arasında paylaşılması güvenli olan yanıtlar için yalnızca public kullanın. no-store, depolanmaması gereken hassas yanıtlar için kullanın.

ASP.NET Core denetleyicisinde, yanıtı döndürmeden önce önbellek üst bilgilerini ayarlayın:

Response.GetTypedHeaders().CacheControl = new Microsoft.Net.Http.Headers.CacheControlHeaderValue
{
    Private = true,
    MaxAge = TimeSpan.FromMinutes(10)
};

Not

no-cache yönergesi depolamaya izin verir, ancak yeniden kullanmadan önce yeniden doğrulama gerektirir. Depolamayı yasaklamak için no-store kullanın.

API, önbellek ilkesini ve yanıtlarındaki doğrulayıcıları denetler. İstemciler ve ara sunucular, önbelleklerini yönetmek için bu bilgileri kullanır. Çağıranların gereksiz veri aktarımları olmadan yanıtları yeniden kullanabilmesi için bu üst bilgileri tutarlı bir şekilde ayarlayın.

max-age belirlemek için, iş yükünün ne kadar güncelliğini yitirmeye dayanabileceğini göz önünde bulundurun. Önbelleğe alınmış yanıt hala yeniyken kaynak değişebilir. Tazelik süresi dolduğunda, önbellek yanıtı atmak ve temsili tamamen yeniden indirmek yerine yeniden doğrulayabilir. Değişikliklerin hemen görünür olmasını gerektiren veriler için uzun bir veri tazelik süresi kullanmayın.

Sorgu işlemeyi iyileştirmek için Etag'ler sağlama

Varlık etiketi (ETag), seçili kaynak gösterimi için opak bir doğrulayıcıdır. İstemciler bunu önbelleğe alınmış bir yanıtla koruyabilir ve gösterimin değişip değişmediğini denetlemek için bunu If-None-Match içinde gönderebilir. Eşleşen GET veya HEAD isteği, yanıt gövdesi olmadan 304 (Değiştirilmedi) döndürür.

Uygulama örnekleri arasında tutarlı kalan ve gösterim değiştiğinde değişen bir doğrulayıcı oluşturun.

Aşağıdaki denetleyici, döndürdüğü tam JSON baytlarının karmalarını oluşturur ve uygulamanın yapılandırılmış JSON seçeneklerini yeniden kullanır. FileContentResult ASP.NET Core, özel sonuç sarmalayıcıları olmadan koşullu yanıt işlemeyi uygular. Depo yalnızca çağıranın okuma yetkisine sahip olduğu bir sipariş döndürür. Ana uygulamada kimlik doğrulama ve yetkilendirmeyi yapılandırın.

using System.Security.Cryptography;
using System.Text.Json;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;
using Microsoft.Net.Http.Headers;

[ApiController]
[Authorize]
[Route("orders")]
public sealed class OrdersController(IOrderRepository repository,IOptions<JsonOptions> jsonOptions) : ControllerBase
{
    [HttpGet("{id:int}")]
    [HttpHead("{id:int}")]
    public async Task<IActionResult> GetOrder(int id, CancellationToken cancellationToken)
    {
        var order = await repository.FindAuthorizedAsync(id, User, cancellationToken);
        if (order is null)
        {
            return NotFound();
        }

        var payload = JsonSerializer.SerializeToUtf8Bytes(order, jsonOptions.Value.JsonSerializerOptions);
        var etag = new EntityTagHeaderValue($"\"{Convert.ToHexString(SHA256.HashData(payload))}\"");

        Response.GetTypedHeaders().CacheControl = new CacheControlHeaderValue
        {
            Private = true,
            MaxAge = TimeSpan.FromMinutes(10)
        };

        return new FileContentResult(payload, "application/json")
        {
            EntityTag = etag
        };
    }
}

Bu örnek, gösterimi arabelleğe alır ve koşullu bir istek için bile sıralamayı okur. Yalnızca sınırlanmış, hassas olmayan yanıtlar için kullanın. Büyük kaynaklar için, seçilen gösterim her değiştiğinde değişen bir depolanmış sürüm belirteci kullanmayı göz önünde bulundurun; böylece tam yükü oluşturmadan bir isteği doğrulayabilirsiniz. İçerik uzlaşımı, sıkıştırma veya ağ geçidi dönüştürmeleri temsili değiştirirse, doğrulayıcıların ve önbellek çeşitliliğinin bu temsil için doğru kaldığından emin olun.

Yanıt, ETag ve önbellek ilkesini içerir. Aşağıdaki örnekler, görüntülenen JSON gövdesinin SHA-256 karmasının ilk 16 onaltılık karakterini (64 bit) gösterir; ardından kısalık için ... gelir. Gerçek başlıklar, üç nokta olmadan tam hash’i içerir.

HTTP/1.1 200 OK
...
Cache-Control: max-age=600, private
Content-Type: application/json
ETag: "3097D1FD51082205..."
Content-Length: 59

{"orderId":2,"productId":4,"quantity":2,"orderValue":10.00}

İpucu

Hassas veriler içeren yanıtlar için kullanın Cache-Control: no-store . Önbelleğe alınabilen kullanıcıya özgü diğer yanıtlar için, paylaşılan önbelleklerde depolamayı önlemek için private kullanın. Uygulamayla ilgili dikkat edilmesi gerekenler için bkz. ASP.NET Core'da yanıt önbelleğe alma ara yazılımı.

Çağıranların değişmemiş bir temsil indirmeden önbelleğe alınmış yanıtları yeniden doğrulamasını sağlayan koşullu GET isteklerini destekleyin. Aşağıdaki istek ve yanıt davranışını uygulayın:

  1. Üst bilgide If-None-Match ETag sağlayan koşullu GET isteklerini kabul edin, örneğin:

    GET https://api.contoso.com/orders/2 HTTP/1.1
If-None-Match: "3097D1FD51082205..."

  2. İstenen kaynağın geçerli ETag değerini (bu örnekte 2. sipariş) koşulla karşılaştırın If-None-Match .

    • Koşul eşleşiyorsa, yanıt gövdesi olmadan 304 (Değiştirilmedi) döndürün.

    • Koşul eşleşmiyorsa, geçerli gösterimle 200 (Tamam) döndürür.

    • İstenen kaynak artık yoksa 404 (Bulunamadı) değerini döndürebilirsiniz.

Not

ETag, yanıtın önbelleğe alınmasını güvenli hale getirmez. Koşullu ve hata yanıtları dahil olmak üzere önbellek yönergelerini tutarlı bir şekilde uygulayın ve hassas veriler için no-store kullanın.

Mümkün olduğunda koşullu istekler için çerçeve desteğini kullanın. Karşılaştırmaları kendiniz uygularsanız, yalnızca ilk etiketi karşılaştırmak yerine sağlanan tüm varlık etiketlerini, joker koşullarını ve zayıf ve güçlü karşılaştırma kurallarını işleyin. 304 (Değiştirilmedi) yanıtlarına uygun ETag ve önbellek üst bilgilerini ekleyin ve kaynak meta verilerini döndürmeden önce yetkilendirme gerçekleştirin.

İpucu

Depolanan bir doğrulama bilgisi, tam kaynağı almadan bir gösterimin değiştirilip değiştirilmediğini denetlemenize olanak sağlayabilir. Bu yaklaşım, kaynak büyük veya alınması pahalı olduğunda veri aktarımını ve işlemeyi azaltabilir.

İyimser eşzamanlılığı desteklemek için ETag'leri kullanın

Kayıp güncelleştirmeleri önlemek için, durum değiştiren isteklerle ilgili If-Match önkoşulları kaynağın geçerli ETag'i ile karşılaştırarak değerlendirin. Bu, API'nin başka bir işlemin daha önce değiştirdiği bir gösterimi temel alan bir değişikliği reddetmesine olanak tanır. Aşağıdaki davranışı uygulayın:

  1. If-Match üst bilgisinde beklenen sürümü tanımlayan güncelleştirme isteklerini kabul edin. Aşağıdaki PUT isteği 2 numaralı siparişi günceller. Önceki GET yanıtının ETag'ini aynı şekilde kısaltılmış olarak kullanır. Etiket, yeni istek gövdesini değil mevcut gösterimi tanımlar:

    PUT https://api.contoso.com/orders/2 HTTP/1.1
If-Match: "3097D1FD51082205..."
Content-Type: application/x-www-form-urlencoded
Content-Length: 37

productId=3&quantity=5&orderValue=250

  2. İstenen kaynağın geçerli ETag değerini (bu örnekte 2. sipariş) If-Match koşuluyla karşılaştırın.

    • Önkoşul eşleşiyorsa güncelleştirmeyi atomik olarak gerçekleştirin ve 204 (İçerik Yok) gibi belgelenmiş başarı yanıtını döndürün. Location Üst bilgi, yalnızca mevcut bir kaynak güncelleştirildi diye gerekli değildir. Yalnızca başarılı bir PUT yanıtında, HTTP'nin depolanmış gösterim için doğrulayıcı gereksinimlerini karşıladığında bir ETag döndürün.

    • Koşul eşleşmiyorsa, 412 (Önkoşul Başarısız oldu) değerini döndürür. Bu örnek yanıt gövdesi döndürmez.

    • Güncelleştirilecek kaynak artık yoksa 404 (Bulunamadı) değerini döndürün.

  3. Çağıranların bir güncelleştirmenin başarılı olup olmadığını veya başka bir değişiklik göndermeden önce geçerli gösterimi almaları gerekip gerekmediğini belirleyebilmesi için başarılı ve çakışma yanıtlarını belgeleyin.

Kayıp güncelleştirmeleri önlemesi gereken işlemler için bir If-Match önkoşulu gerektirmelidir ve eksik olduğunda 428 (Önkoşul Gerekli) değerini döndürebilirsiniz. If-Match için güçlü karşılaştırma kullanın.

Uygulama belleğinde bir sürümün denetlenip koşulsuz olarak kaydedilmesi bir yarış durumu oluşturur. Veri deposunda sürüm karşılaştırmasını ve yazma işlemini atomik olarak uygulayın. Örneğin, güncelleştirmenin yalnızca depolanan sürüm hâlâ isteği değerlendirmek için kullanılan sürümle eşleşiyorsa başarılı olması için bir veritabanı eşzamanlılık belirteci kullanın.

Entity Framework (EF) Core'da, eşzamanlı bir değişikliğin üzerine yazmak yerine bir eşzamanlılık belirteci yapılandırın ve DbUpdateConcurrencyException işlemini ele alın. API'nin veri erişim kodunda, işlemin semantiği buna izin vermedikçe beklenen sürümü otomatik olarak değiştirmeyin ve çakışan bir veritabanı güncelleştirmesini yeniden denemeyin. Daha fazla bilgi için bkz. Eşzamanlılık çakışmalarını işleme.

Büyük istekleri ve yanıtları işleme

Büyük istek ve yanıt gövdeleri API belleğini, bant genişliğini ve bağlantı kapasitesini kullanır. Büyük aktarımların hizmeti tüketmemesi için streaming ve kaynak limitleri uygulayın. Önemli miktarda veriyi işlerken aşağıdaki noktaları göz önünde bulundurun:

Büyük nesneler içeren istek ve yanıtları en iyi duruma getirme

Görüntüler veya diğer ikili veriler gibi büyük nesneler için akış halinde karşıya yükleme ve indirmeyi destekleyin.

Eşzamansız akış API'lerini kullanın ve sunucunun anlaşmaya varılan HTTP sürümü için aktarım çerçevesini seçmesine izin verin. Transfer-Encoding: chunked öğesini yanıtın her parçasına el ile eklemeyin. Akış, HTTP/1.1 öbekli kodlama ile sınırlı değildir. Uygulama belleğinde tüm sınırlandırılmamış isteği veya yanıtı arabelleğe almayı önleyin.

Uygulama ve barındırma katmanlarında istek gövdesi sınırları, karşıya yükleme sınırları, zaman aşımları ve iptal ilkeleri ayarlayın. Yanıtı başlatmadan önce 413 (İçerik Çok Büyük) ile büyük boyutlu bir isteği reddedin.

HTTP sıkıştırması, sunucu ve istemcide ek işleme maliyetine bağlı olarak aktarım boyutunu azaltabilir. Örneğin, bir istemci Accept-Encoding: gzip gönderebilir. Sunucu gzip ile sıkıştırılmış içerik döndürüyorsa Content-Encoding: gzip kullanarak kodlamayı tanımlayın.

Barındırma platformu veya ara yazılım aracılığıyla sıkıştırmayı yapılandırın ve hem istemci hem de sunucu tarafında CPU ve bant genişliği dengelerini ölçün.

  • Zaten sıkıştırılmış biçimleri yeniden sıkıştırmaktan kaçının.
  • Dinamik olarak oluşturulan HTTPS yanıtları için sıkıştırmayı etkinleştirmeden önce BREACH gibi sıkıştırma risklerini değerlendirin ve uygun azaltma önlemlerini uygulayın. Ara yazılımınızda HTTPS sıkıştırmasını devre dışı bıraksanız bile barındırma sunucunuz sıkıştırma uygulamak üzere yapılandırılmış olabilir.
  • İçerik kodlama değiştiğinde önbellek varyasyonlarının ve ETag'lerin doğru kaldığından emin olun.

Sıkıştırma uygulama yönergeleri ve güvenlik konuları için bkz. ASP.NET Core'de yanıt sıkıştırma.

Büyük kaynakların kısmi indirilmelerini destekleme

API büyük kaynakların kısmi indirilmelerini destekliyorsa, bu özelliği Accept-Ranges ile belirtin. Yanıt gövdesi olmadan, toplam Content-Length dahil olmak üzere kaynağın meta verilerini döndürerek HEAD isteklerini işleyin. Desteklenen bir bayt aralığı belirten GET istekleri için, 206 (Kısmi İçerik), döndürülen bölüm için bir Content-Length ve kaynağın döndürülen bu bölümünü tanımlayan bir Content-Range döndürün. Bu yanıt sözleşmesi, çağıranların API'nin tüm nesneyi döndürmesine gerek kalmadan kaynağın bölümlerini almasını sağlar.

HTTP HEAD istekleri ve kısmi yanıtlar API tasarımında daha ayrıntılı olarak açıklanmıştır.

Büyük yüklemeler için 100-Continue işle

Büyük bir HTTP/1.1 yüklemesi için, istemci Expect: 100-continue içeren istek üst bilgilerini gönderebilir ve gövdeyi iletmeden önce bekleyebilir. Sunucu, tam gövdeyi almadan geçici 100 (Devam) yanıtı gönderebilir veya isteği reddedebilir. Bu iletişim, bir ön boş isteğin ardından gelen ikinci bir tam istek değil, tek bir isteğin parçasıdır.

Barındırma yığınının ve ağ geçidinin, istekleri Expect: 100-continue ile ve olmadan nasıl işlediğini yapılandırın ve test edin. API bir yüklemeyi kabul ettiğinde veya reddettiğinde davranışını doğrulayın ve sunucu kaynağı kullanımı üzerindeki etkileri ve istek gecikme süresini ölçün.

Çok sayıda nesne döndürebilecek istekler için sayfalandırma desteği

Büyük bir koleksiyonun tamamının alınması sunucu işlemeyi, ağ trafiğini ve gecikme süresini artırabilir.

Sunucudaki sayfalama girdilerini doğrulayın ve maksimum sayfa boyutunu zorunlu kılın. Aşağıdaki denetleyici istek doğrulamasını gösterir. Varsayılan olarak 10 sonuç olur ve 1 ile 100 arasında olmayan limitleri veya 0 ile 10.000 arasında olmayan ofsetleri reddeder. Bu sınırlar örnek niteliğindedir. İş yüküne ve yük testlerine göre sınırları seçin. [ApiController] kullandığınızda doğrulama hataları 400 yanıtı üretir. Daha fazla bilgi için bkz. ASP.NET Core ile web API'leri oluşturma.

using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Authorize]
[Route("orders")]
public sealed class OrderCollectionsController(IOrderRepository repository) : ControllerBase
{
    [HttpGet]
    public async Task<ActionResult<IReadOnlyList<Order>>> GetOrders(
        [FromQuery, Range(1, 100)] int limit = 10,
        [FromQuery, Range(0, 10000)] int offset = 0,
        CancellationToken cancellationToken = default)
    {
        var orders = await repository.ListAuthorizedAsync(limit, offset, User, cancellationToken);
        return Ok(orders);
    }
}

İstemci, https://api.contoso.com/orders?limit=30&offset=50 kullanarak, 50 ofsetinden başlayan 30 sipariş isteyebilir.

Önceki örnekte gösterilen istek doğrulamasının ötesinde, yanıt sözleşmesine bir sonraki sayfa bağlantısı veya devam belirteci ekleyin. Örneğin, başka bir sayfa kullanılabilir olduğunda nextLink özelliği https://api.contoso.com/orders?limit=30&offset=80 olarak ayarlanmış siparişleri döndürebilirsiniz. Bağlantıdaki filtreleri, sıralama düzenini ve API sürümünü koruyun. nextLink öğesini atlayın veya son sayfada null olarak ayarlayın. Sonraki bağlantı sözleşmesi örneği için bkz. sayfalama Microsoft Graph.

Tüm koleksiyonu yükledikten sonra değil, veri deposunda filtreleme ve sayfalandırma uygulayın. Deterministik bir sıralama düzeni kullanın. Büyük veya sık değişen koleksiyonlar için, pahalı ofsetleri ve kararsız sayfa sınırlarını önlemek amacıyla imleç tabanlı sayfalamayı değerlendirin.

İpucu

Sorgu karmaşıklığı, filtre ifadeleri ve istek boyutu üzerindeki belgelenmiş sınırları uygulayın. İstek yolundaki her ağ geçidi, ara sunucu ve sunucunun sınırlarını test edin.

Yanıt hızı, ölçeklenebilirlik ve kullanılabilirliği sürdürme

API'nin kritik işlemleri için gecikme süresi, aktarım hızı ve kullanılabilirlik hedeflerini tanımlayın. Beklenen trafik, ani artışlar ve bağımlılık hataları için tasarlayın ve test edin. Yatay ölçeklendirme ve durum bilgisi olmayan işleme bu hedefleri destekler. Aşağıdaki uygulama gereksinimlerini göz önünde bulundurun.

Uzun süreli istekler için asenkron destek sağlama

Normal bir HTTP isteğinden daha uzun süren bir iş için isteği doğrulayın ve yetkilendirin, işi kalıcı olarak kaydedin ve 202 (Kabul Edildi) döndürün. Yanıt sonrasında bitmek üzere izlenmeyen bir işlem içi göreve güvenmeyin: uygulamanın yeniden başlatılması, ölçeğin azaltılması ve dağıtım bunu kesintiye uğratabilir. Bu olaylara rağmen çalışmanın çalışmaya devam etmesi gerektiğinde dayanıklı bir kuyruk ve worker veya dayanıklı bir iş akışı kullanın. Tam HTTP semantiği ve uygulama kılavuzu için bkz. Zaman uyumsuz İstek-Yanıt deseni.

Çağıranların işlemin durumunu ve sonucunu alması için bir yol sağlayın. API, işleme tamamlandığında çağıranları da bilgilendirebilir.

İstemcilerin düzenli olarak sorgulayacağı bir durum kaynağı sağlayabilirsiniz:

  1. Müşteri isteği gönderir. Çalışmayı kabul etmeden önce girdisini ve erişim izinlerini doğrulayın.
  2. Bir işlem tanımlayıcısını ve durumunu, Azure Tablo Depolaması gibi dayanıklı bir depolama alanında kalıcı olarak saklayın ve örneğin Azure Service Bus kullanarak ayrı bir işlemci için çalışmayı sıraya alın. Kabul edilen çalışmanın kaybına neden olmaması için kalıcılığı ve kuyruğa almayı, bu iki işlem arasında oluşan bir hata durumunda koordine edin.
  3. Durum uç noktasını tanımlayan bir Location üst bilgi ve yoklama sıklığını denetleen bir Retry-After üst bilgi ile 202 döndürür. İsteği yalnızca çalışma kalıcı olarak kaydedildikten sonra kabul edin.
  4. Çalışan işlemi işler ve dayanıklı durumunu güncelleştirir. Bir çalışan aynı işi birden çok kez alabileceğinden işlemeyi idempotent yapın. Geçici hatalara sınırlı sayıda yeniden deneme uygulayın.
  5. İstemci durum uç noktasını yoklar. Hem durum hem de sonuç uç noktaları üzerinde kaynak düzeyinde yetkilendirmeyi zorunlu kılın. Tahmin edilemeyen tanımlayıcı yetkilendirme değildir.
  6. Çalışma devam ederken belgelenmiş bir durum gösterimi döndürün. Tamamlandığında, sonucu veya bir sonuç kaynağına 303 (See Other) yeniden yönlendirmesi sağlayın. Tutarlı ve güvenli bir hata işleme sözleşmesi aracılığıyla hataları bildirin.
  7. İşlem kayıtları ve sonuçları için bekletme ve temizleme tanımlayın. Belge işlemi süresinin dolması, yinelenen gönderimler ve desteklenen iptal davranışı.

Bağlı istemciler için tamamlama bildirimleri için ASP.NET Core SignalR kullanmayı göz önünde bulundurun. İstemcilerin bağlantı kesildikten veya kaçırılan bir bildirimden sonra kurtarılabilmesi için dayanıklı durum kaynağını kullanılabilir durumda tutun. Daha fazla bilgi için bkz. ASP.NET Core SignalR'ye genel bakış.

Her bir isteğin durum bilgisiz olduğundan emin olun

Önceki bir istekle aynı uygulama örneğine ulaşmak için daha sonraki bir istek gerektirmeyin. İş akışını ve kaynak durumunu yalnızca işlem belleğinde değil uygun paylaşılan depolarda tutun. İstekler, sunucu örneğine bağımlılık oluşturmadan dayanıklı kaynak durumuna bağlı olabilir. Durumsuz istek işleme, yatay ölçeklendirmeyi destekler.

Alt bağımlılıklarınızı anlayın

Her aşağı akış çağrısı için bir zaman aşımı ayarlayın. Çağrılar, yeniden denemeler ve gecikmeler için toplam süreyi API isteğinin zaman aşımı süresi içinde tutun ve istek iptalini alt işlemlere iletin.

Yalnızca yinelemesi güvenli olan geçici hataları ve işlemleri yeniden deneyin. Artan bekleme süresi ve rastgelelik içeren sınırlı yeniden denemeler kullanın. Bağımlılık başına toplam yeniden deneme sayısını ve istek başına denemeleri sınırlayın. Daha fazla bilgi için bkz . Geçici hata işleme.

Yinelenen bağımlılık hataları API kapasitesini tüketebilirken devre kesici kullanın.

DoS saldırılarının olasılığını azaltmak için istemcileri izleyin ve hız sınırlaması uygulayın.

İstek hızı, eşzamanlılık, yük ve yürütme süresi sınırları uygulayın. Mümkün olduğunda sınırları kimliği doğrulanmış çağıran veya kiracıya göre bölümlendirin. Çağıran istemci yapılandırılmış istek sınırını aştığında 429 (Çok Fazla İstek) ve hizmetin geçici olarak kullanılamadığı durumlarda 503 (Hizmet Kullanılamıyor) değerini döndürür. Uygun yerlerde Retry-After ekleyin. API, aşağı akış bağımlılıklarına yapılan çağrıları yeniden denerse, bu yeniden denemeleri aşırı yüklemeyi artırmayacak şekilde sınırla.

Ağ geçidi ve uygulama sınırları farklı amaçlara hizmet eder. Ağ geçidi sınırları paylaşılan kapasiteyi koruyabilir. Limitler, işlem maliyetini ve sonraki aşama kapasitesini yansıtabilir. Ağ katmanı DDoS korumasının veya web uygulaması güvenlik duvarının yerini ikisi de değiştirmez. Daha fazla bilgi için Kısıtlama deseni bölümüne bakın.

Kalıcı HTTP bağlantılarını dikkatli bir şekilde yönetme

Gelen bağlantılar için, iş yükü ve ağ yolu için sunucu ve ağ geçidi etkin tutma zaman aşımlarını, istek zaman aşımlarını ve eşzamanlı bağlantı sınırlarını yapılandırın. Bağlantıları her yanıt sonrasında rutin olarak kapanmaya zorlamayın. ASP.NET Core sunucu ayarları hakkında bilgi için bkz. Kestrel web sunucusu için seçenekleri yapılandırma.

API'nin kendisi downstream HTTP servislerini çağırırsa, bu giden bağlantıları yeniden kullanın. Bir .NET API uygulamasında, uygun bir HttpClient ile uzun ömürlü PooledConnectionLifetime örnekleri kullanın veya IHttpClientFactory tarafından oluşturulan istemcileri kullanın. Artık gerekli olmadığında giden yanıt iletilerini ve akışlarını atın. Bu ayarlar, gelen istemci bağlantıları için değil API'nin alt çağrıları için geçerlidir. Ayrıntılar ve tanımlama bilgisi işleme uyarıları için bkz. HttpClient kullanma yönergeleri.

Web API’si yayımlama ve yönetme

API'yi işletimsel gereksinimlerini karşılayan bir barındırma ortamında dağıtıma alın. Aşağıdaki stratejileri göz önünde bulundurun:

  • HTTPS kullanın. Korumalı uç noktalara yönelik isteklerin kimliğini doğrulayın ve her kaynak ile işlem için yetkilendirmeyi zorunlu kılın.
  • Talep değiştikçe yanıt süresi taahhütlerini karşılamak için barındırma ortamını ölçeklendirin.
  • API'nin faturalama modeli gerektiriyorsa istekleri ölçün.
  • Trafiği düzenleyin ve gerektiğinde istemci kotalarını uygulayın.
  • Uyumluluk ve olay yanıtının gerektirdiği denetim olaylarını kaydedin, ancak kimlik bilgilerini, belirteçleri veya hassas istek ve yanıt gövdelerini günlüğe kaydetmeyin.
  • Ana bilgisayar durumunu izleyin ve sağlıksız bir ana bilgisayarı yeniden başlatma gibi kurtarma eylemlerini tanımlayın.

Ortak yönetimle ilgili hususları işleyen ve doğrulanmış istekleri API'ye ileten ayrı bir façade kullanmayı göz önünde bulundurun. Bir cephe aşağıdaki özellikleri sağlayabilir:

  • Birden çok web API'si için tümleştirme noktası olarak hareket etme.
  • Çeşitli teknolojiler kullanılarak oluşturulan istemciler için iletileri dönüştürme ve iletişim protokollerini çevirme.
  • Web API’sini barındıran sunucu üzerindeki yükü azaltmak üzere istekleri ve yanıtları önbelleğe alma.

API sözleşmelerini ve ağ geçidi yapılandırmasını sürüm denetimi altında tutun, dağıtım işlem hatlarındaki değişiklikleri doğrulayın ve geri alma yordamlarını tanımlayın. Barındırma, kimlik, ağ ve idareyi kuruluşun landing zone yaklaşımıyla uyumlu hale getirme. Daha fazla bilgi için bkz. Azure giriş bölgesi nedir?.

Web API'sini test etme

API'nin mantığını doğrulamak için birim testlerini ve HTTP davranışını doğrulamak için tümleştirme testlerini kullanın.

Aşağıdaki denetimleri ekleyin:

  • Doğru işlemleri çağırdığını onaylamak üzere tüm yolları test edin. Özellikle 405 (Yönteme İzin Verilmiyor) HTTP durum kodunun beklenmedik bir şekilde döndürülmekte olduğunu unutmayın. Bu durum kodu, bir rota ile o rotaya yönlendirilebilen HTTP yöntemleri (GET, POST, PUT, DELETE) arasındaki uyuşmazlığı gösterebilir.

    Her rota tarafından desteklenmeyen yöntemleri kullanan istekler gönderin ve belgelenmiş 405 (Yönteme İzin Verilmedi) yanıtını ve Allow üst bilgisini doğrulayın.

  • Tüm yolların uygun şekilde korunduğunu ve uygun kimlik doğrulama ile yetkilendirme denetimlerine tabi olduğunu doğrulayın.

    Not

    Güvenliğin kullanıcı kimlik doğrulaması gibi bazı yönleri büyük olasılıkla web API'sinden çok konak ortamının sorumluluğundadır, ancak yine de dağıtım işleminin bir parçası olarak güvenlik testlerini eklemeniz gerekir.

  • Her bir işlem tarafından gerçekleştirilen özel durum işlemeyi test edin ve istemci uygulamaya uygun ve anlamlı bir HTTP yanıtının geri gönderildiğini doğrulayın.

  • İstek ve yanıt iletilerinin doğru oluşturulduğunu onaylayın. Örneğin, kaynak oluşturan bir POST isteği için seri durumdan çıkarma, ayrıştırma, kaynak oluşturma ve yanıtın Location üst bilgisini doğrulayın.

  • Desteklenen ve desteklenmeyen istek medya türlerini yanıt içeriği uzlaşımından ayrı olarak test edin. Desteklenmeyen istek biçimleri için 415 (Desteklenmeyen Medya Türü) yanıtlarını ve hatalı biçimlendirilmiş gövdeler için belgelenen doğrulama hatalarını doğrulayın.

  • Yönlendirme, istek doğrulama ve yanıt şeması da dahil olmak üzere desteklenen tüm API sürümlerini test edin. Atlanan, hatalı biçimlendirilmiş ve desteklenmeyen sürüm tanımlayıcılarını test edin ve önbelleğe alınan yanıtların sürüm sınırlarını aşmadığını doğrulayın.

  • Yanıt iletilerindeki tüm bağlantıları ve URI'leri doğrulayın. Örneğin, bir HTTP POST iletisi yeni oluşturulan kaynağın URI'sini döndürmelidir. Tüm HATEOAS bağlantıları geçerli olmalıdır.

  • Her işlemin farklı giriş birleşimleri için doğru durum kodlarını döndürdüğünden emin olun. Örneğin:

    • Bir sorgu başarılı olursa, 200 (Tamam) durum kodunu döndürmelidir.
    • Kaynak bulunamazsa, işlem 404 (Bulunamadı) HTTP durum kodunu döndürmelidir.
    • İstemci bir kaynağı başarıyla silen bir istek gönderirse durum kodu 204 (İçerik Yok) olmalıdır.
    • İstemci yeni bir kaynak oluşturan bir istek gönderirse, durum kodu 201 (Oluşturuldu) olmalıdır.

    Uygulama veya barındırma katmanından beklenmeyen 5xx yanıtları araştırın.

  • Bir istemci uygulamanın belirtebildiği farklı istek üst bilgisi birleşimlerini test edin ve web API’sinin yanıt iletilerinde beklenen bilgileri döndürdüğünden emin olun.

  • Sorgu dizelerini test edin. bir işlem isteğe bağlı parametreler (sayfalandırma istekleri gibi) alabiliyorsa, farklı birleşimleri ve parametrelerin sırasını test edin.

  • Zaman uyumsuz işlemlerin başarıyla tamamlandığını doğrulayın. Akış yanıtları için API'nin yükün tamamını arabelleğe almadığını ve istemci bağlantı kesmelerini ve iptal işlemlerini doğru işlediğini doğrulayın. API uzun süre çalışan işlemler için durum kaynakları sağlıyorsa, durum kaynaklarının işlemin ilerleme durumunu ve sonuçlarını doğru şekilde raporladığını doğrulayın.

Doğruluğu etkileyen hata ve sınır durumlarını test edin:

  • Minimum, maksimum, negatif, hatalı biçimlendirilmiş ve aşırı sayfalama ile batch girdilerini doğrulayın.
  • Son sayfaya kadar sayfalandırma bağlantılarını izleyin. Bağlantıların sorgu seçeneklerini koruduğunu ve belgelenen tamamlama sinyalinin döndürüldüğünü doğrulayın.
  • Ek giriş alanlarının korumalı özellikleri değiştiremediğini ve alan seçiminin yetkisiz verileri kullanıma sunmadığını doğrulayın.
  • Eşleştirme, eşleşmeyen, zayıf, çoklu ve joker karakterli ETag'leri test edin ve 304 yanıtın gövde içermediğini doğrulayın.
  • Eşzamanlı güncelleştirmeler yapın ve veri deposunun eski sürümden gelen yazma işlemlerini atomik olarak reddettiğini onaylayın.
  • Arayanların başka bir çağıranın kaynaklarını, durum kayıtlarını veya önbelleğe alınmış yanıtlarını okuyamadığını doğrulayın.
  • Çok kiracılı API'ler için sahte veya eşleşmeyen kiracı tanımlayıcılarını test edin. Önbelleğe alma etkinleştirildiğinde, farklı kiracılardan aynı kaynak URI'sine yönelik istekleri test edin.
  • Zaman aşımlarını, istemci iptalini, bağımlılık hatalarını, çalışan yeniden başlatmalarını ve arka plan çalışmalarının yinelenen teslimatını simüle edin.
  • Aşağı akış zaman aşımı ve yeniden deneme bütçelerini, iptali ve devre kesici kurtarmayı doğrulayın.
  • 429 (Çok Fazla İstek Var) ve 503 (Hizmet Kullanılamıyor)yanıtlarını, yeniden deneme davranışını ve aşırı yüklenmiş istekleri reddetme maliyetini doğrulayın.

Üretim benzeri altyapı ve gerçekçi işlem karışımlarına karşı yük testleri çalıştırın. Aktarım hızı, gecikme yüzdelikleri, hata oranları ve kaynak doygunluğu için geçme ve kalma ölçütlerini tanımlayın. Azure Yük Testi kullanın ve regresyon denetimlerini dağıtım işlem hattıyla tümleştirin.

API Management kullanımı

İlke zorlamalı yönetilen bir ağ geçidine ihtiyacınız olduğunda Azure API Management kullanmayı göz önünde bulundurun. İstek yoluna maliyet, başka bir ağ atlama ve bağımlılık ekler. Kapasite, ağ, kullanılabilirlik ve bölgesel gereksinimlere göre bir hizmet katmanı ve topolojisi seçin; özellikler katmana göre farklılık gösterir. Geliştirici katmanı üretim iş yüklerine yönelik değildir. API Management için Well-Architected hizmet kılavuzunu izleyin.

Şu adımları tamamlayarak bir web API'sini yayımlayabilir ve yönetebilirsiniz:

  1. Web API'sini Azure App Service, Azure Container Apps, Azure Kubernetes Service (AKS) veya Azure Sanal Makineler gibi bir barındırma platformuna dağıtın.

  2. API Management'ı, istekleri ağ geçidi URL'sinden arka uç API'sine yönlendirecek şekilde yapılandırın. Bir API Management örneği, istekleri birden çok API'ye yönlendirebilir. Uygulamaların farklı erişim sınırlarına ihtiyacı olduğunda birden çok örnek aynı arka uç API'sini de kullanıma açabilir.

    Not

    Yanıtlardaki HATEOAS bağlantıları arka uç sunucu URL'sine değil API Management ağ geçidi URL'sine başvurmalıdır.

  3. Sürüm denetimli bir OpenAPI tanımını içeri aktarın ve içeri aktarılan işlemlerin, parametrelerin, güvenlik gereksinimlerinin ve yanıt şemalarının uygulamayla eşleşip eşleşmediğini doğrulayın. Desteklenen OpenAPI sürümlerini ve içeri aktarma sınırlamalarını denetleyin. Daha fazla bilgi için bkz. OpenAPI belirtimlerini içeri aktarma.

  4. Hem istemciden ağ geçidine hem de ağ geçidi ile arka uç arasındaki iletişim için kimlik doğrulamasını ve yetkilendirmeyi yapılandırın. OAuth 2.0 erişim belirteçlerini doğrulayın ve istemci istekleri için gerekli izinleri zorunlu kılın. Microsoft Entra ID kimlik doğrulamasını destekleyen arka uçlar için api Management yönetilen kimliğini yalnızca ihtiyaç duyduğu izinlerle tercih edin. Sertifika kimlik doğrulaması başka bir seçenektir. Daha güvenli seçenekler varsa Temel kimlik doğrulamasından kaçının. Daha fazla bilgi için bkz. Azure API Management'da API'ler için kimlik doğrulaması ve yetkilendirme.

    Not

    API Management abonelik anahtarları gerekiyorsa, bunları kimlik doğrulaması ve kaynak düzeyinde yetkilendirme yerine kullanmayın.

  5. Kimlik doğrulaması, kaynaklar arası erişim, ileti dönüştürmeleri, IP filtreleme, hız sınırları ve kotalar için gereken politikaları yapılandırın. Yanıt önbelleğini yalnızca önbelleğe alınabilecek güvenli veriler için yapılandırın. İlkeleri uygun kapsamda uygulayın ve her işlem için fiilen nasıl çalıştıklarını doğrulayın.

Daha fazla bilgi için API Management belgelerine bakın.

Önemli

Ağ geçidi arka ucu özel yapmaz veya kaynak düzeyi yetkilendirmesinin yerini almaz. Ağ geçidi de dahil olmak üzere iş yükünün tamamı için arka uç erişim denetimlerini, hata işlemeyi, kapasiteyi ve gözlemlenebilirliği tasarlayın. Seçilen katmanın özelliklerine göre bölge ve bölgesel yedekliliği değerlendirin. Maliyet modeline ağ geçidi ücretlerini, telemetri alımını ve saklamayı ve veri aktarımını dahil edin.

İstemci tarafı geliştiricileri destekleme

API tüketicilerine kimlik doğrulaması, işlemler, parametreler, veri türleri ve yanıt kodları için belgeler sağlayın.

Bir web API’sinin REST işlemlerini belgeleme

API'nin işlemlerini, parametrelerini, istek ve yanıt şemalarını ve güvenlik gereksinimlerini açıklayan bir OpenAPI tanımı yayımlayın. Gerçeklemeyle birlikte sürüm denetimi altında tutun ve API'nin gerçek davranışıyla eşleşip eşleşmediğini doğrulayın.

Tüketicilerin API'yi doğru kullanması için gereken yönergelerle API referansını tamamlayın:

  • Her işlem için kimlik doğrulaması gereksinimleri ve izinleri.
  • Örnek istekler, başarılı yanıtlar ve hata yanıtları.
  • Giriş doğrulama kuralları, yük verisi sınırları, sayfalandırma ve oran sınırları.
  • Zaman aşımı davranışı, yeniden deneme güvenliği ve tüm idempotensi gereksinimleri.
  • Uzun süre çalışan işlemler için durum ve sonuç alma.
  • Sürüm oluşturma ve uyumluluk beklentileri.

API sözleşmesi değiştiğinde belgeleri ve örnekleri güncel tutun.

İstemci SDK’sını uygulama

API tüketicileri için bir SDK sağlamayı göz önünde bulundurun. SDK, istekleri oluşturan, yanıtları ayrıştıran ve API'nin belgelenmiş hatalarını gösteren türü belirtilmiş yöntemleri kullanıma açabilir.

API'nin OpenAPI tanımından tipli istemciler oluşturmayı göz önünde bulundurun, ancak oluşturulan davranışı hizmete karşı doğrulayın. Belge kimlik doğrulaması, zaman aşımları, iptal, sayfalandırma, hata yanıtları ve hangi işlemlerin yeniden denenmesi güvenlidir. İstemci ve API uyumluluk ilkesini uyumlu tutun. Oluşturulan kod tümleştirme testlerine olan ihtiyacı ortadan kaldırmaz.

Web API'sini izleme

API'yi, bağımlılıklarını ve herhangi bir ağ geçidini birlikte izleyin. Hizmet düzeyi hedeflerini ve uyarılarını yalnızca konak durumunu temel alarak değil müşteri etkisine göre tanımlayın.

Web API'sini doğrudan izleme

İzlemeleri, ölçümleri ve günlükleri toplamak ve sinyalleri Application Insights'a veya desteklenen başka bir arka uca dışarı aktarmak için OpenTelemetry izlemesini kullanın. .NET, Node.js ve Python izlemesi için Microsoft OpenTelemetry Distro yönergelerini izleyin. Java, Azure İzleyici OpenTelemetry Distro'yu kullanır. Dile özgü OpenTelemetry etkinleştirme kılavuzunu izleyin.

API davranışını açıklayan sinyalleri izleyin:

  • İşleme göre istek hacmi, hata oranı ve gecikme yüzdelikleri
  • Bağımlılık gecikmeleri, başarısızlıklar ve zaman aşımları
  • Oran sınırı nedeniyle reddetmeler, eşzamanlı çalışma ve kaynak doygunluğu
  • arka plan işlemi kuyruğunun yaşı, tamamlanma süresi, başarısızlıklar ve yeniden denemeler
  • Önbelleğe alma tasarımın bir parçası olduğunda önbellek verimliliği

Bir izleme aracının otomatik olarak topladığı telemetri, dile, kitaplıklara ve yapılandırmaya bağlı olarak değişir. Etki alanı işlemleri ve arka plan çalışması için enstrümantasyon ekleyin. Tarayıcı oturumlarının, kullanıcı rollerinin veya tüm istek ayrıntılarının otomatik olarak kullanılabilir olduğunu varsaymayın. İz bağlamını ağ geçidi, uygulama ve çalışanlar arasında yayın. Tanılama gereksinimlerini, veri duyarlılığını ve telemetri maliyetini dengelemek için örnekleme ve saklamayı yapılandırın.

Uygun durumlarda yinelenen dış denetimler için Application Insights Standart kullanılabilirlik testlerini kullanın. Hassas verileri göstermeden anlamlı bir sağlık veya işletim uç noktasını denetleyin, eyleme dönüştürülebilir uyarılar tanımlayın ve bir yanıt runbook'u koruyun.

API Management kullanarak web API'sini izleme

Ağ geçidi hatalarını arka uç hatalarından ayırmak için API Management tarafından desteklenen Azure İzleyici ölçümlerini, günlüklerini, analizlerini ve tanılamalarını kullanın. Ağ geçidi ve uygulama telemetrisini ilişkilendirin ve ilke hatalarını, kapasiteyi, istek gecikme süresini ve kısıtlamayı izleyin. Kullanılabilir sinyaller katmana ve ağ geçidi yapılandırmasına bağlıdır.

API Management içinWell-Architected hizmet kılavuzundaki gözlemlenebilirlik ve kapasite önerilerini izleyin.

Sonraki adımlar

  • Son güncelleştirme: