ABP Framework ile Adım Adım Yazılım Geliştirme – Bölüm 6: API Katmanı Geliştirme

Admin 8 Haziran 2025

Modern uygulamalarda API (Application Programming Interface) katmanı, hem istemci uygulamalar (mobil, web) hem de diğer servislerle iletişim kurmak için kritik öneme sahiptir. ABP Framework, güçlü ve kolay yapılandırılabilir bir API katmanı oluşturmanızı sağlar. Bu bölümde, ABP’nin API geliştirme özelliklerini ve en iyi pratikleri inceleyeceğiz.

Auto API Controller Özellikleri

ABP Framework’ün en kullanışlı özelliklerinden biri Auto API Controllers‘dır. Eğer bir uygulama servisi IApplicationService arayüzünü implemente ediyorsa ve uygun kurallara uyuyorsa, ABP otomatik olarak bu servis için bir ASP.NET Core API denetleyicisi oluşturur. Bu, manuel olarak denetleyici (controller) yazma ihtiyacını ortadan kaldırır ve geliştirme hızını artırır.

BookAppService (Bkz. Bölüm 5) gibi bir servis, otomatik olarak bir Books API denetleyicisine dönüştürülür ve /api/app/books gibi endpoint’ler oluşturulur.
CRUD operasyonları (Get, GetList, Create, Update, Delete) için HTTP metotları (GET, POST, PUT, DELETE) otomatik olarak eşleştirilir.

API Endpoint’lerin Özelleştirilmesi

Otomatik API denetleyicileri büyük kolaylık sağlasa da, bazen endpoint’leri veya HTTP metotlarını özelleştirmek isteyebilirsiniz. Bunu çeşitli yollarla yapabilirsiniz:

[RemoteService(IsEnabled = false)]: Uygulama servisinin otomatik API endpoint’leri oluşturmasını engeller.
[Route("api/my-custom-path/books")]: Otomatik olarak oluşturulan rota (route) yolunu özelleştirir.
[HttpMethod(HttpVerb.Get)] veya [HttpGet]: Uygulama servis metotlarına doğrudan HTTP metot nitelikleri ekleyerek HTTP fiilini ve hatta özel rotaları belirleyebilirsiniz.

Örnek:

using Volo.Abp.AspNetCore.Mvc;
using Volo.Abp.Application.Services;
using Volo.Abp.AspNetCore.Mvc.Annotations; // [HttpMethod] için

public class BookAppService : ApplicationService, IBookAppService
{
    // ...

    [HttpGet] // GET metodu olarak ayarlar
    [Route("api/app/books/by-type/{type}")] // Özel rota belirleme
    public async Task<List<BookDto>> GetBooksByTypeAsync(BookType type)
    {
        var books = await _bookRepository.GetListAsync(b => b.Type == type);
        return ObjectMapper.Map<List<Book>, List<BookDto>>(books);
    }
}

Swagger Entegrasyonu ve API Dokümantasyonu

ABP Framework, API’leriniz için otomatik olarak Swagger (OpenAPI) dokümantasyonu oluşturur ve bunu yayınlar. Bu, API’lerinizi kolayca test etmenizi ve anlaşılır bir şekilde belgelendirmenizi sağlar.

YourProjectName.Web veya YourProjectName.HttpApi projesinde SwaggerModule veya benzeri bir yapılandırma ile Swagger UI etkinleştirilir.
Uygulamanızı çalıştırdığınızda /swagger adresine giderek API dokümantasyonunu ve test arayüzünü görebilirsiniz.
XML dokümantasyonu aktif edilerek, uygulama servis metotlarınıza ve DTO’larınıza eklediğiniz yorumlar Swagger UI’da görüntülenebilir.

API Versiyonlama

Uygulamanız büyüdükçe veya harici tüketicilerle paylaştıkça API versiyonlama önemli hale gelir. ABP Framework, ASP.NET Core’un yerleşik API versiyonlama mekanizmalarını destekler (URI, sorgu dizesi, başlık).

URI Versiyonlama (Önerilen): [ApiVersion("1.0")] niteliği ve rota tanımlamalarında {version:apiVersion} placeholder’ı kullanılır.
YourProjectNameHttpApiHostModule veya benzeri bir modülde versiyonlama seçenekleri yapılandırılır.

// Controller'da versiyonlama
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/app/books")]
public class BookAppService : ApplicationService, IBookAppService
{
    // ...
}

Request ve Response Formatları

ABP Framework, JSON formatını varsayılan olarak destekler. HTTP POST/PUT isteklerinde JSON payload’larını otomatik olarak DTO’lara bağlar ve API yanıtlarını JSON olarak döndürür. İhtiyaç halinde XML veya diğer formatlar da yapılandırılabilir.

API Güvenlik Ayarları (CORS, Authentication)

API katmanı, uygulamanızın güvenliğini sağlamak için kritik öneme sahiptir.

CORS (Cross-Origin Resource Sharing): Farklı bir alan adından gelen JavaScript isteklerinin API’nize erişmesine izin vermek için kullanılır. appsettings.json veya YourProjectNameWebModule/YourProjectNameHttpApiHostModule içinde CORS politikaları tanımlanır. C#// YourProjectNameWebModule.cs'de veya HttpApiHostModule.cs'de public override void ConfigureServices(ServiceConfigurationContext context) { // ... context.Services.AddCors(options => { options.AddDefaultPolicy(builder => { builder .WithOrigins( configuration["App:CorsOrigins"] .Split(",", StringSplitOptions.RemoveEmptyEntries) .ToArray() ) .WithAbpExposedHeaders() .SetIsOriginAllowedToAllowWildcardSubdomains() .AllowAnyHeader() .AllowAnyMethod() .AllowCredentials(); }); }); // ... }
Authentication (Kimlik Doğrulama): Kullanıcının kimliğini doğrulamak için kullanılır. ABP, Identity Server (OpenIddict) ile tam entegrasyon sunar (Bkz. Bölüm 8). API’ler genellikle JWT (JSON Web Token) tabanlı kimlik doğrulama kullanır.
Authorization (Yetkilendirme): Kimliği doğrulanmış bir kullanıcının belirli bir kaynağa erişim veya bir işlemi yapma yetkisine sahip olup olmadığını kontrol eder. [Authorize] niteliği veya politika tabanlı yetkilendirme kullanılır. C#using Microsoft.AspNetCore.Authorization; public class BookAppService : ApplicationService, IBookAppService { [Authorize(MyProjectPermissions.Books.Create)] // Sadece belirli bir izni olan kullanıcılar erişebilir public async Task<BookDto> CreateAsync(CreateUpdateBookDto input) { // ... } }

API Testleri ve Postman Koleksiyonu Oluşturma

API katmanını geliştirdikten sonra, doğru çalıştığından emin olmak için test etmek önemlidir.

Unit/Integration Testler: ABP’nin test altyapısını kullanarak uygulama servislerinizi veya API denetleyicilerinizi test edebilirsiniz (Bkz. Bölüm 14).
Postman/Insomnia: Popüler API test araçları olan Postman veya Insomnia ile API endpoint’lerinize manuel istekler gönderebilir ve yanıtları inceleyebilirsiniz.
Postman Koleksiyonları: Tekrarlayan testler için Postman koleksiyonları oluşturarak, API testlerinizi düzenli ve otomatize edebilirsiniz. Otomatik olarak oluşturulan API endpoint’leri sayesinde Swagger UI’dan doğrudan Postman koleksiyonu dışa aktarabilirsiniz.

API katmanı, uygulamanızın dış dünyaya açılan yüzüdür ve doğru bir şekilde tasarlanması ve güvenliğinin sağlanması büyük önem taşır.

Erkan AKGÜN