{"id":30129,"date":"2025-09-24T02:30:28","date_gmt":"2025-09-23T23:30:28","guid":{"rendered":"https:\/\/fatihsoysal.com\/blog\/net-web-apide-api-surumleme-tam-bir-rehber\/"},"modified":"2025-09-24T02:30:28","modified_gmt":"2025-09-23T23:30:28","slug":"net-web-apide-api-surumleme-tam-bir-rehber","status":"publish","type":"post","link":"https:\/\/fatihsoysal.com\/blog\/net-web-apide-api-surumleme-tam-bir-rehber\/","title":{"rendered":".NET Web API’de API S\u00fcr\u00fcmleme: Tam Bir Rehber"},"content":{"rendered":"

.NET Web API’de API S\u00fcr\u00fcmleme: Tam Bir Rehber<\/p>\n

Web API’lerinizin zaman i\u00e7inde nas\u0131l evrilece\u011fini ve yeni \u00f6zellikler eklerken veya mevcut i\u015flevleri de\u011fi\u015ftirirken eski istemcilerinizi nas\u0131l destekleyece\u011finizi hi\u00e7 d\u00fc\u015f\u00fcnd\u00fcn\u00fcz m\u00fc? Bu, bir\u00e7ok geli\u015ftirici i\u00e7in ba\u015f a\u011fr\u0131s\u0131na neden olan bir sorundur. \u0130\u015fte tam da bu noktada API s\u00fcr\u00fcmlemesi devreye girer. Bu makale, .NET Web API’lerinde API s\u00fcr\u00fcmlemenin farkl\u0131 y\u00f6ntemlerini, avantajlar\u0131n\u0131, dezavantajlar\u0131n\u0131 ve en iyi uygulamalar\u0131 ad\u0131m ad\u0131m a\u00e7\u0131klayarak, bu karma\u015f\u0131k konuyu basitle\u015ftirmeyi hedefliyor.<\/p>\n

.NET Web API S\u00fcr\u00fcmlemesinin Temelleri: Neden \u00d6nemli?<\/h2>\n

API s\u00fcr\u00fcmlemesi, API’nizin farkl\u0131 s\u00fcr\u00fcmlerini ayn\u0131 anda desteklemenizi sa\u011flayan bir stratejidir. Bu, mevcut istemcilerinizi k\u0131rmadan yeni \u00f6zellikler eklemenize, hata d\u00fczeltmeleri yapman\u0131za veya API tasar\u0131m\u0131n\u0131z\u0131 iyile\u015ftirmenize olanak tan\u0131r. Yeni bir \u00f6zellik eklemek veya mevcut bir \u00f6zelli\u011fi de\u011fi\u015ftirmek istedi\u011finizde, yeni bir API s\u00fcr\u00fcm\u00fc olu\u015fturmak yerine eski s\u00fcr\u00fcm\u00fc de\u011fi\u015ftirmek, uyumlu olmayan istemcilerinizin \u00e7al\u0131\u015fmas\u0131n\u0131 durdurabilece\u011fi i\u00e7in risklidir. \u00d6rne\u011fin, bir mobil uygulama eski API s\u00fcr\u00fcm\u00fcn\u00fc kullan\u0131yorsa ve siz aniden API’nizi de\u011fi\u015ftirirseniz, bu uygulaman\u0131n \u00e7al\u0131\u015fmas\u0131 durur. API s\u00fcr\u00fcmlemesi sayesinde, eski ve yeni istemciler sorunsuz bir \u015fekilde \u00e7al\u0131\u015fmaya devam edebilir. Ayr\u0131ca, farkl\u0131 istemciler farkl\u0131 API \u00f6zelliklerine ihtiya\u00e7 duyabilir, bu nedenle s\u00fcr\u00fcmleme, bu gereksinimleri kar\u015f\u0131lamak i\u00e7in esneklik sa\u011flar. \u0130yi bir API s\u00fcr\u00fcmleme stratejisi, API’nizin uzun vadeli s\u00fcrd\u00fcr\u00fclebilirli\u011fini ve istemcilerinizin memnuniyetini sa\u011flar.<\/p>\n

API S\u00fcr\u00fcmleme Stratejileri: Hangisini Se\u00e7melisiniz?<\/h2>\n

.NET Web API’lerinde API s\u00fcr\u00fcmlemesi i\u00e7in birka\u00e7 farkl\u0131 strateji vard\u0131r. En yayg\u0131n olanlar\u0131 URI’da s\u00fcr\u00fcmleme, HTTP ba\u015fl\u0131klar\u0131nda s\u00fcr\u00fcmleme ve Cabecera s\u00fcr\u00fcmlemesidir. Her stratejinin kendi avantajlar\u0131 ve dezavantajlar\u0131 vard\u0131r ve se\u00e7iminiz, API’niz ve istemcilerinizin ihtiya\u00e7lar\u0131na ba\u011fl\u0131d\u0131r.<\/p>\n

URI’da S\u00fcr\u00fcmleme: Basit ve Anla\u015f\u0131l\u0131r Bir Yakla\u015f\u0131m<\/h3>\n

Bu y\u00f6ntem, URL’nin bir par\u00e7as\u0131 olarak API s\u00fcr\u00fcm\u00fcn\u00fc belirtmeyi i\u00e7erir. \u00d6rne\u011fin, \/api\/v1\/products<\/code> s\u00fcr\u00fcm 1’i, \/api\/v2\/products<\/code> ise s\u00fcr\u00fcm 2’yi temsil eder. Bu, basit ve anla\u015f\u0131labilir bir y\u00f6ntemdir, ancak URL’ler zaman i\u00e7inde daha uzun hale gelebilir. Ayr\u0131ca, istemciler taraf\u0131ndan URI’n\u0131n de\u011fi\u015ftirilmesi gerekebilir. Yeni s\u00fcr\u00fcmler olu\u015fturmak nispeten kolayd\u0131r, ancak URL’nin de\u011fi\u015ftirilmesi nedeniyle istemci taraf\u0131nda g\u00fcncellemeler gerekli olacakt\u0131r. Bu y\u00f6ntemle;<\/p>\n

[Route(\"api\/v{version:int}\/products\")]\npublic class ProductsController : ApiController\n{\n    \/\/ ...\n}<\/pre>\n
<\/code><\/p>\n
gibi bir route tan\u0131mlamas\u0131yla s\u00fcr\u00fcm y\u00f6netimi sa\u011flanabilir.  v{version:int}<\/code> k\u0131sm\u0131, s\u00fcr\u00fcm numaras\u0131n\u0131 URL'den yakalay\u0131p, do\u011fru controller'a y\u00f6nlendirir.<\/p>\n
HTTP Ba\u015fl\u0131klar\u0131nda S\u00fcr\u00fcmleme: Daha Esnek Bir Yakla\u015f\u0131m<\/h3>\n
Bu strateji, API isteklerinin HTTP ba\u015fl\u0131klar\u0131nda s\u00fcr\u00fcm bilgilerini ta\u015f\u0131may\u0131 i\u00e7erir.  Bu, URI'leri temiz tutman\u0131za olanak tan\u0131r, ancak istemcinin do\u011fru ba\u015fl\u0131\u011f\u0131 eklemesi gerekti\u011fi i\u00e7in daha fazla dikkat gerektirir. \u00d6rne\u011fin, Accept<\/code> ba\u015fl\u0131\u011f\u0131, istemcinin istedi\u011fi API s\u00fcr\u00fcm\u00fcn\u00fc belirtebilir. Bu y\u00f6ntem, URI'leri temiz tutmak a\u00e7\u0131s\u0131ndan olduk\u00e7a avantajl\u0131d\u0131r, ancak istemcilerin do\u011fru ba\u015fl\u0131\u011f\u0131 eklemeleri gerekti\u011fi i\u00e7in dikkat gerektirir.  Bu, ayn\u0131 URI'yi farkl\u0131 s\u00fcr\u00fcmler i\u00e7in kullanman\u0131za izin verir. Daha esnektir, ancak istemci taraf\u0131nda daha fazla kod gerektirir.   \u00d6rnek bir uygulama \u015f\u00f6yle olabilir;<\/p>\n
public class ProductsController : ApiController\n{\n    public IHttpActionResult Get()\n    {\n        var version = Request.Headers.Accept.FirstOrDefault(a => a.MediaType == \"application\/vnd.company.product.v1+json\");\n        if(version != null) {\n            \/\/ S\u00fcr\u00fcm 1 i\u015flemleri\n        }\n        else{\n            \/\/ Varsay\u0131lan veya en son s\u00fcr\u00fcm i\u015flemleri\n        }\n        return Ok();\n    }\n}<\/pre>\n
<\/code>\n<\/p>\n
Cabecera S\u00fcr\u00fcmlemesi: Custom Header Kullan\u0131m\u0131<\/h3>\n
Bu y\u00f6ntem, \u00f6zel bir HTTP ba\u015fl\u0131\u011f\u0131 kullanarak s\u00fcr\u00fcmlemeyi y\u00f6netir.  \u00d6rne\u011fin, X-API-Version<\/code> ba\u015fl\u0131\u011f\u0131n\u0131 kullanarak, s\u00fcr\u00fcm numaras\u0131n\u0131 g\u00f6nderebilirsiniz.  Bu y\u00f6ntem, HTTP ba\u015fl\u0131klar\u0131nda s\u00fcr\u00fcmleme y\u00f6ntemine benzer, ancak daha \u00f6zelle\u015ftirilebilirdir. Bu y\u00f6ntem, \u00f6zellikle kendi \u00f6zel s\u00fcr\u00fcmleme \u015femalar\u0131n\u0131z\u0131 uygulamak istedi\u011finizde avantajl\u0131d\u0131r.<\/p>\n
Uygulamal\u0131 K\u0131s\u0131m: URI S\u00fcr\u00fcmlemesi ile Basit Bir \u00d6rnek<\/h2>\n
\u015eimdi, URI s\u00fcr\u00fcmlemesini kullanarak basit bir .NET Web API \u00f6rne\u011fi olu\u015ftural\u0131m.  Bu \u00f6rnekte, \u00fcr\u00fcn bilgilerini d\u00f6nd\u00fcren bir API olu\u015fturaca\u011f\u0131z.  \u0130ki farkl\u0131 s\u00fcr\u00fcm olu\u015fturaca\u011f\u0131z: s\u00fcr\u00fcm 1 ve s\u00fcr\u00fcm 2. S\u00fcr\u00fcm 2, ek bir alan i\u00e7erecek \u015fekilde \u00fcr\u00fcn bilgilerini geni\u015fletecektir.<\/p>\n
\u00d6ncelikle, yeni bir ASP.NET Web API projesi olu\u015fturun.  Ard\u0131ndan, a\u015fa\u011f\u0131daki kodlar\u0131 ProductsController.cs<\/code> dosyas\u0131na ekleyin:<\/p>\n
using System.Collections.Generic;\nusing System.Web.Http;\n\nnamespace ApiVersioningExample.Controllers\n{\n    [RoutePrefix(\"api\/v{version:int}\/products\")]\n    public class ProductsController : ApiController\n    {\n        [HttpGet]\n        public IHttpActionResult Get(int version)\n        {\n            if (version == 1)\n            {\n                return Ok(new List\n                {\n                    new ProductV1 { Id = 1, Name = \"Product 1\" },\n                    new ProductV1 { Id = 2, Name = \"Product 2\" }\n                });\n            }\n            else if (version == 2)\n            {\n                return Ok(new List\n                {\n                    new ProductV2 { Id = 1, Name = \"Product 1\", Description = \"Description 1\" },\n                    new ProductV2 { Id = 2, Name = \"Product 2\", Description = \"Description 2\" }\n                });\n            }\n            else\n            {\n                return NotFound();\n            }\n        }\n    }\n\n    public class ProductV1\n    {\n        public int Id { get; set; }\n        public string Name { get; set; }\n    }\n\n    public class ProductV2\n    {\n        public int Id { get; set; }\n        public string Name { get; set; }\n        public string Description { get; set; }\n    }\n}<\/pre>\n
<\/code><\/p>\n
Bu kod, farkl\u0131 s\u00fcr\u00fcm numaralar\u0131na g\u00f6re farkl\u0131 Product s\u0131n\u0131flar\u0131n\u0131 d\u00f6nd\u00fcr\u00fcr.  RoutePrefix<\/code> attribute'\u00fc,  api\/v1\/products<\/code> veya api\/v2\/products<\/code> gibi URL'leri yakalar.<\/p>\n
\u0130leri D\u00fczey Teknikler: Content Negotiation ve MediaType Kullan\u0131m\u0131<\/h2>\n
Daha geli\u015fmi\u015f API s\u00fcr\u00fcmleme senaryolar\u0131 i\u00e7in Content Negotiation kullanmak daha g\u00fc\u00e7l\u00fc bir \u00e7\u00f6z\u00fcm sunar.  Bu y\u00f6ntemde, istemci iste\u011finde Accept<\/code> header'\u0131n\u0131 kullanarak istedi\u011fi medya tipini ve dolay\u0131s\u0131yla API s\u00fcr\u00fcm\u00fcn\u00fc belirtir.  Bu, URI'leri temiz tutarken daha esnek bir s\u00fcr\u00fcmleme sa\u011flar.  \u00d6rne\u011fin; application\/vnd.companyname.product-v1+json<\/code> medya tipi, s\u00fcr\u00fcm 1'i, application\/vnd.companyname.product-v2+json<\/code> ise s\u00fcr\u00fcm 2'yi temsil edebilir.<\/p>\n
Bu yakla\u015f\u0131m,  s\u00fcr\u00fcmleri y\u00f6netmek i\u00e7in daha fazla kontrol sa\u011flar ve ayn\u0131 zamanda istemcilerin tercih ettikleri veri format\u0131n\u0131 belirtmelerine olanak tan\u0131r.  Ancak, implementasyonu URI s\u00fcr\u00fcmlemesinden daha karma\u015f\u0131kt\u0131r.  Daha fazla bilgi i\u00e7in Fatih Soysal'\u0131n blogunu<\/a> inceleyebilirsiniz.<\/p>\n
Performans Kar\u015f\u0131la\u015ft\u0131rmas\u0131: Farkl\u0131 Y\u00f6ntemlerin Performans Etkileri<\/h2>\n
Her s\u00fcr\u00fcmleme y\u00f6nteminin performans etkisi farkl\u0131d\u0131r.  URI s\u00fcr\u00fcmlemesi, en basit y\u00f6ntem oldu\u011fu i\u00e7in genellikle en iyi performans\u0131 sunar.  HTTP ba\u015fl\u0131klar\u0131 veya Content Negotiation y\u00f6ntemleri, sunucu taraf\u0131ndan daha fazla i\u015flem gerektirdi\u011fi i\u00e7in biraz daha yava\u015f olabilir.  Ancak, bu performans fark\u0131 genellikle \u00f6nemsizdir.  \u00d6nemli olan, API'nizin genel performans\u0131 i\u00e7in daha uygun olan y\u00f6ntemi se\u00e7mektir.<\/p>\n
G\u00fcvenlik Uyar\u0131lar\u0131: API S\u00fcr\u00fcmlemesinde G\u00fcvenlik A\u00e7\u0131klar\u0131<\/h2>\n
\n  Dikkat!<\/b> API s\u00fcr\u00fcmleme stratejinizi se\u00e7erken, g\u00fcvenlik a\u00e7\u0131klar\u0131n\u0131 \u00f6nlemeye dikkat edin.  \u00d6rne\u011fin, g\u00fcvenlik a\u00e7\u0131klar\u0131ndan ka\u00e7\u0131nmak i\u00e7in do\u011fru kimlik do\u011frulama ve yetkilendirme mekanizmalar\u0131n\u0131 kullan\u0131n. Eski s\u00fcr\u00fcmleri uzun s\u00fcre desteklemek, g\u00fcvenlik riskini art\u0131rabilir.  G\u00fcvenlik g\u00fcncellemeleri eski s\u00fcr\u00fcmlerde desteklenmeyebilir.\n<\/div>\n<\/p>\n
\u00d6\u011frenme Yol Haritas\u0131<\/h2>\n
Yeni Ba\u015flayanlar \u0130\u00e7in:<\/h3>\n