REST API Development Properly

5.1 REST API mental model

REST’i ilk aşamada karmaşık bir akademik tanım gibi düşünmeyelim. Bizim için REST, dış dünyanın MiniBank kaynaklarıyla HTTP üzerinden konuşmasıdır. Bir müşteri oluşturmak, bir hesabı görüntülemek, hesap listesini almak veya transfer başlatmak gibi işlemler birer API davranışıdır.

Yeni başlayan ekiplerde sık görülen hata, endpoint’leri method adı gibi tasarlamaktır: /createAccount, /getAccount, /deleteAccount. REST tarafında daha temiz yaklaşım ise kaynağı URL’de, yapılacak işi HTTP method’da anlatmaktır.

/createAccount
/getAccountById
/deleteAccount
/updateCustomer

POST   /api/accounts
GET    /api/accounts/{id}
DELETE /api/accounts/{id}
PUT    /api/customers/{id}

Bu yaklaşım sadece estetik değildir. API contract net olduğunda frontend, mobil uygulama, başka microservice veya test otomasyonu bu API’yi daha kolay tüketir. Hatalı status code veya dağınık endpoint isimleri küçük projede sorun yaratmayabilir; ama servis sayısı arttıkça operasyonel maliyete dönüşür.

5.2 @RestController ne yapmalı, ne yapmamalı?

@RestController, gelen HTTP request’i Java metoduna bağlayan sınıftır. Ama controller business logic’in merkezi değildir. Controller’ın işi request’i almak, temel request mapping’i sağlamak, validation’ı tetiklemek, service’i çağırmak ve uygun response dönmektir.

@RestController
@RequestMapping("/api/accounts")
public class AccountController {

    private final AccountApplicationService accountApplicationService;

    public AccountController(AccountApplicationService accountApplicationService) {
        this.accountApplicationService = accountApplicationService;
    }

    @PostMapping
    public ResponseEntity<AccountResponse> create(@Valid @RequestBody AccountCreateRequest request) {
        AccountResponse response = accountApplicationService.createAccount(request);
        return ResponseEntity.status(HttpStatus.CREATED).body(response);
    }

    @GetMapping("/{accountNo}")
    public ResponseEntity<AccountResponse> getByAccountNo(@PathVariable String accountNo) {
        return ResponseEntity.ok(accountApplicationService.getAccount(accountNo));
    }
}

5.3 DTO Pattern: Entity dış contract değildir

DTO, API’nin dış dünyaya verdiği sözdür. Entity ise çoğunlukla veritabanı ve persistence modeliyle ilgilidir. Bu ikisini aynı obje üzerinden yönetmek başlangıçta hızlı görünebilir ama uzun vadede ciddi sorun üretir.

Örneğin AccountEntity içinde teknik alanlar, internal status değerleri, audit kolonları veya lazy relation’lar olabilir. Entity’yi doğrudan response olarak dönersen bu alanları istemeden dışarı açabilirsin. Ayrıca entity değiştiğinde API contract’ın da değişmiş olur. Bu, client tarafında beklenmeyen kırılmalara yol açar.

public record AccountCreateRequest(
    @NotBlank(message = "Müşteri numarası boş olamaz")
    String customerNo,

    @NotBlank(message = "Para birimi boş olamaz")
    @Pattern(regexp = "TRY|USD|EUR", message = "Para birimi TRY, USD veya EUR olmalıdır")
    String currency
) {}

public record AccountResponse(
    String accountNo,
    String customerNo,
    String currency,
    BigDecimal balance,
    String status
) {}

5.4 Validation: Hatalı request business logic’e ulaşmadan durmalı

Validation iki seviyede düşünülmeli. Birinci seviye request’in şekli ve temel kurallarıdır: alan boş mu, format doğru mu, sayı pozitif mi, uzunluk uygun mu? Bunları request DTO üzerinde annotation ile ifade ederiz. İkinci seviye ise business validation’dır: müşteri gerçekten var mı, hesap aktif mi, transfer limiti yeterli mi? Bunlar service katmanında kalmalıdır.

@NotBlank
@Size
@Pattern
@Positive
@Email

Müşteri var mı?
Hesap aktif mi?
Bakiye yeterli mi?
Transfer limiti uygun mu?

@Validated ise özellikle service metotlarında method-level validation veya validation group kullanmak istediğimizde gündeme gelir. Bu modülde controller request validation’ı ana akışımız olacak; sonraki modüllerde business exception handling ile bunu tamamlayacağız.

5.5 Proper HTTP Status Codes

Status code, API’nin client ile konuştuğu ortak dildir. Body içinde “success: false” yazmak tek başına yeterli değildir. Client önce HTTP seviyesindeki sonucu okur, sonra gerekirse body içindeki detaylara bakar.

5.6 DTO Mapping: Manual mı MapStruct mı?

DTO kullandığımızda kaçınılmaz olarak mapping ihtiyacı doğar. Küçük projelerde manual mapping yeterince açık ve kontrol edilebilirdir. Daha büyük projelerde çok sayıda benzer mapping tekrarına düşüyorsak MapStruct gibi compile-time mapper araçları değerlendirilebilir.

@Component
public class AccountDtoMapper {

    public AccountResponse toResponse(Account account) {
        return new AccountResponse(
            account.accountNo(),
            account.customerNo(),
            account.currency(),
            account.balance(),
            account.status()
        );
    }
}

MiniBank eğitiminde ilk aşamada manual mapper kullanacağız. Çünkü amacımız mapping tool öğretmek değil, API contract ve katman ayrımını netleştirmek. İlerleyen aşamada istenirse MapStruct ayrı bir iyileştirme olarak eklenebilir.