REST tabanlı web hizmeti kullanma

Makale
02/25/2025

Temsili Durum Aktarımı (REST), web hizmetleri oluşturmaya yönelik bir mimari stildir. REST istekleri genellikle web tarayıcılarının web sayfalarını almak ve sunuculara veri göndermek için kullandığı HTTP fiilleri kullanılarak HTTPS üzerinden yapılır. Fiiller şunlardır:

GET – Bu işlem web hizmetinden veri almak için kullanılır.
POST – Bu işlem web hizmetinde yeni bir veri öğesi oluşturmak için kullanılır.
PUT – Bu işlem web hizmetindeki bir veri öğesini güncelleştirmek için kullanılır.
PATCH – Bu işlem, öğenin nasıl değiştirilmesi gerektiğiyle ilgili bir dizi yönerge açıklanarak web hizmetindeki bir veri öğesini güncelleştirmek için kullanılır.
DELETE – Bu işlem web hizmetindeki bir veri öğesini silmek için kullanılır.

REST'e bağlı web hizmeti API'leri şu şekilde tanımlanır:

Temel URI.
GET, POST, PUT, PATCH veya DELETE gibi HTTP yöntemleri.
Veriler için JavaScript Nesne Gösterimi (JSON) gibi bir medya türü.

REST tabanlı web hizmetleri genellikle istemciye veri döndürmek için JSON iletilerini kullanır. JSON, veri gönderirken bant genişliği gereksinimlerinin azalmasına neden olan, kompakt yükler üreten metin tabanlı bir veri değişim biçimidir. REST'in basitliği, mobil uygulamalarda web hizmetlerine erişmek için birincil yöntem haline getirmesine yardımcı oldu.

Dekont

Bir web hizmetine erişmek için genellikle zaman uyumsuz programlama gerekir. Zaman uyumsuz programlama hakkında daha fazla bilgi için bkz . Async ve await ile zaman uyumsuz programlama.

Web hizmeti işlemleri

Örnek REST hizmeti ASP.NET Core kullanılarak yazılır ve aşağıdaki işlemleri sağlar:

İşlem	HTTP yöntemi	Göreli URI	Parametreler
Yapılacaklar öğelerinin listesini alma	GET	/api/todoitems/
Yeni yapılacaklar öğesi oluşturma	POST	/api/todoitems/	JSON biçimli TodoItem
Yapılacaklar öğesini güncelleştirme	PUT	/api/todoitems/	JSON biçimli TodoItem
Yapılacaklar öğesini silme	DELETE	/api/todoitems/{id}

.NET MAUI uygulaması ve web hizmeti, görüntülenen ve depolama için web hizmetine gönderilen verileri modellemek için sınıfını kullanır TodoItem :

public class TodoItem
{
    public string ID { get; set; }
    public string Name { get; set; }
    public string Notes { get; set; }
    public bool Done { get; set; }
}

ID özelliği her TodoItem nesneyi benzersiz olarak tanımlamak için kullanılır ve web hizmeti tarafından güncelleştirilecek veya silinecek verileri tanımlamak için kullanılır. Örneğin, kimliği 6bb8a868-dba1-4f1a-93b7-24ebce87e243olan öğesini silmek TodoItem için .NET MAUI uygulaması öğesine https://hostname/api/todoitems/6bb8a868-dba1-4f1a-93b7-24ebce87e243bir DELETE isteği gönderir.

Web API çerçevesi bir istek aldığında, isteği bir eyleme yönlendirir. Bu eylemler sınıfındaki TodoItemsController genel yöntemlerdir. Web API çerçevesi, gelen isteklerin URL'lerini eşleştirmek ve bunları eylemlerle eşlemek için yönlendirme ara yazılımını kullanır. REST API'leri, işlemleri HTTP fiilleri ile temsil edilen bir kaynak kümesi olarak uygulamanın işlevselliğini modellemek için öznitelik yönlendirmesini kullanmalıdır. Öznitelik yönlendirme, eylemleri doğrudan yol şablonlarıyla eşlemek için bir dizi öznitelik kullanır. Öznitelik yönlendirme hakkında daha fazla bilgi için bkz . REST API'leri için öznitelik yönlendirme. ASP.NET Core kullanarak REST hizmeti oluşturma hakkında daha fazla bilgi için bkz . Yerel mobil uygulamalar için arka uç hizmetleri oluşturma.

HTTPClient nesnesini oluşturma

.NET Çok Platformlu Uygulama Kullanıcı Arabirimi (.NET MAUI) uygulaması, sınıfıyla HttpClient web hizmetine istek göndererek REST tabanlı bir web hizmetini kullanabilir. Bu sınıf, TANıMLANAN bir URI kaynağından HTTP istekleri göndermek ve HTTP yanıtları almak için işlevsellik sağlar. Her istek zaman uyumsuz bir işlem olarak gönderilir.

Nesne, HttpClient uygulamanın HTTP istekleri yapması gerektiği sürece dayanması için sınıf düzeyinde bildirilmelidir:

public class RestService
{
    HttpClient _client;
    JsonSerializerOptions _serializerOptions;

    public List<TodoItem> Items { get; private set; }

    public RestService()
    {
        _client = new HttpClient();
        _serializerOptions = new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
            WriteIndented = true
        };
    }
    ...
}

JsonSerializerOptions nesnesi, web hizmetinden alınan ve web hizmetine gönderilen JSON yükünün biçimlendirmesini yapılandırmak için kullanılır. Daha fazla bilgi için bkz . How to instantiate JsonSerializerOptions instances with System.Text.Json.

Veri alma

HttpClient.GetAsync yöntemi, URI tarafından belirtilen web hizmetine get isteği göndermek ve ardından yanıtı web hizmetinden almak için kullanılır:

public async Task<List<TodoItem>> RefreshDataAsync()
{
    Items = new List<TodoItem>();

    Uri uri = new Uri(string.Format(Constants.RestUrl, string.Empty));
    try
    {
        HttpResponseMessage response = await _client.GetAsync(uri);
        if (response.IsSuccessStatusCode)
        {
            string content = await response.Content.ReadAsStringAsync();
            Items = JsonSerializer.Deserialize<List<TodoItem>>(content, _serializerOptions);
        }
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }

    return Items;
}

Veriler web hizmetinden nesne HttpResponseMessage olarak alınır. Durum kodu, üst bilgiler ve herhangi bir gövde dahil olmak üzere yanıt hakkındaki bilgileri içerir. REST hizmeti, HTTP isteğinin başarılı veya başarısız olup olmadığını belirtmek için yanıtında HttpResponseMessage.IsSuccessStatusCode özelliğinden alınabilen bir HTTP durum kodu gönderir. Bu işlem için REST hizmeti, isteğin başarılı olduğunu ve istenen bilgilerin yanıtta olduğunu belirten HTTP durum kodu 200 'i (Tamam) yanıta gönderir.

HTTP işlemi başarılı olursa yanıtın içeriği okunur. HttpResponseMessage.Content özelliği yanıtın içeriğini temsil eder ve türündedirHttpContent. sınıfı, HttpContent VE gibi Content-Type Content-EncodingHTTP gövdesini ve içerik üst bilgilerini temsil eder. İçerik daha sonra yöntemi kullanılarak HttpContent.ReadAsStringAsync öğesine string okunur. string daha sonra JSON'dan bir List nesneye seri durumdan TodoItem çıkarılır.

Uyarı

ReadAsStringAsync Büyük bir yanıt almak için yönteminin kullanılması performansı olumsuz etkileyebilir. Bu gibi durumlarda, tam arabelleğe almak zorunda kalmamak için yanıt doğrudan seri durumdan çıkarılmalıdır.

Veri oluşturma

HttpClient.PostAsync yöntemi, URI tarafından belirtilen web hizmetine post isteği göndermek ve ardından yanıtı web hizmetinden almak için kullanılır:

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
    Uri uri = new Uri(string.Format(Constants.RestUrl, string.Empty));

    try
    {
        string json = JsonSerializer.Serialize<TodoItem>(item, _serializerOptions);
        StringContent content = new StringContent(json, Encoding.UTF8, "application/json");

        HttpResponseMessage response = null;
        if (isNewItem)
            response = await _client.PostAsync(uri, content);
        else
            response = await _client.PutAsync(uri, content);

        if (response.IsSuccessStatusCode)
            Debug.WriteLine(@"\tTodoItem successfully saved.");
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }
}

Bu örnekte örnek, TodoItem web hizmetine göndermek üzere bir JSON yüküne seri hale getirilmiştir. Bu yük daha sonra, istek yöntemiyle yapılmadan önce web hizmetine gönderilecek HTTP içeriğinin gövdesine PostAsync eklenir.

REST hizmeti, HTTP isteğinin başarılı veya başarısız olup olmadığını belirtmek için yanıtında HttpResponseMessage.IsSuccessStatusCode özelliğinden alınabilen bir HTTP durum kodu gönderir. Bu işlemin tipik yanıtları şunlardır:

201 (OLUŞTURULDU) – İstek, yanıt gönderilmeden önce yeni bir kaynak oluşturulmasıyla sonuçlandı.
400 (BAD REQUEST) – istek sunucu tarafından anlaşılmıyor.
409 (ÇAKıŞMA) – sunucudaki bir çakışma nedeniyle istek gerçekleştirilemedi.

Verileri güncelleştirme

HttpClient.PutAsync yöntemi, URI tarafından belirtilen web hizmetine put isteği göndermek ve ardından yanıtı web hizmetinden almak için kullanılır:

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  response = await _client.PutAsync(uri, content);
  ...
}

yönteminin PutAsync işlemi, web hizmetinde veri oluşturmak için kullanılan yöntemle aynıdır PostAsync . Ancak, web hizmetinden gönderilen olası yanıtlar farklılık gösterir.

204 (İçERİk YOK) – İstek başarıyla işlendi ve yanıt kasıtlı olarak boş.
400 (BAD REQUEST) – istek sunucu tarafından anlaşılmıyor.
404 (BULUNAMADı) – İstenen kaynak sunucuda yok.

Veri silme

HttpClient.DeleteAsync yöntemi, URI tarafından belirtilen web hizmetine bir DELETE isteği göndermek ve ardından yanıtı web hizmetinden almak için kullanılır:

public async Task DeleteTodoItemAsync(string id)
{
    Uri uri = new Uri(string.Format(Constants.RestUrl, id));

    try
    {
        HttpResponseMessage response = await _client.DeleteAsync(uri);
        if (response.IsSuccessStatusCode)
            Debug.WriteLine(@"\tTodoItem successfully deleted.");
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }
}

204 (İçERİk YOK) – İstek başarıyla işlendi ve yanıt kasıtlı olarak boş.
400 (BAD REQUEST) – istek sunucu tarafından anlaşılmıyor.
404 (BULUNAMADı) – İstenen kaynak sunucuda yok.

Yerel geliştirme

ASP.NET Core Web API gibi bir çerçeveyle yerel olarak bir REST web hizmeti geliştiriyorsanız, web hizmetinizde ve .NET MAUI uygulamanızda aynı anda hata ayıklayabilirsiniz. Bu senaryoda, Web hizmetinizi Android öykünücülerinden ve iOS simülatörlerinden HTTP üzerinden kullanmak için .NET MAUI uygulamanızda düz metin HTTP trafiğini etkinleştirmeniz gerekir. Daha fazla bilgi için bkz. Android öykünücülerinden ve iOS simülatörlerinden yerel web hizmetlerine Bağlan.

Aracılığıyla paylaş