Merhaba arkadaşlar, bugün sizlere bir backend projemde yaşadığım bir mimari karar anımı anlatacağım. Uzun süredir REST API'ler tasarlıyorum ve her seferinde "HATEOAS" (Hypermedia as the Engine of Application State) konusu kafamı karıştırıyordu. Teoride harika, uygulamada ise frontend ekibinden gelen "Abi linkler nerede, bu response çok karmaşık" serzenişleriyle baş başa kalıyordum. İşte tam bu sırada, daha yapılandırılmış ve pratik bir standart olan JSON:API'yi keşfettim ve implemente ettim. Gelin size bu yolculuğu anlatayım.
Neden HATEOAS Değil de JSON:API?
HATEOAS, gerçekten de "ideal" REST'in son adımı. Her kaynağa ait işlemler için link'ler döndürüyor. Ancak, özellikle karmaşık ilişkili verilerde (örneğin, bir kullanıcının yazıları, yorumları, beğenileri) response'u okunması ve parse edilmesi zor bir hale getirebiliyordu. Ayrıca, frontend tarafında bu dinamik link'leri işleyecek generic bir client yazmak, projenin ilk aşamalarında büyük bir overhead'ti. JSON:API ise kesin kuralları, tutarlı yapısı ve include parametresi gibi özellikleriyle hem backend geliştiricisine hem de frontend geliştiricisine net bir yol haritası çiziyor.
Temel Yapıyı Kurmak (Laravel Örneği)
Implementasyona Laravel üzerinden devam ettim. İlk iş, harika bir paket olan laravel-json-api/laravel paketini projeye eklemek oldu. Bu paket, spesifikasyonu büyük ölçüde otomatik olarak karşılıyor.
Kurulumdan sonra, ilk kaynak şemamızı oluşturalım. Diyelim ki bir Post modelimiz var.
Gördüğünüz gibi, modelimizin alanlarını, filtrelerini ve en önemlisi includePaths ile hangi ilişkilerin tek istekte getirilebileceğini tanımladık. Bu, N+1 sorgu problemini önlemek için çok kritik.
Frontend'te Hayat Nasıl Kolaylaştı?
Backend'i bu şekilde ayarladıktan sonra, frontend (Vue.js) tarafında işler inanılmaz derecede standartlaştı. Artık tüm endpoint'ler tutarlı bir yapıda yanıt veriyor. İşte tipik bir get isteği ve response'u:
İstek: `GET /api/v1/posts/123?include=author,comments.user`
Bu yapının en güzel tarafı, included dizisi. Tek bir istekle ana post'u, yazarını, yorumları ve hatta yorum sahiplerini bile aldık. Frontend'te state yönetimi ve cache'leme işlemleri bu standart yapı sayesinde çok daha öngörülebilir hale geldi.
Sonuç ve Düşüncelerim
JSON:API, özellikle orta ve büyük ölçekli projelerde takım içindeki iletişimi ve geliştirme hızını inanılmaz artırdı. HATEOAS'ın esnekliğinden ödün verdiğiniz doğru, ancak karşılığında muazzam bir tutarlılık ve geliştirici deneyimi (DX) kazanıyorsunuz. Spesifikasyonun sorting, filtering, pagination gibi konuları da standartlaştırması, API dokümantasyon yükünü de azaltıyor.
Siz backend geliştiriciler, REST API'lerinizde HATEOAS mı kullanıyorsunuz yoksa JSON:API veya GraphQL gibi daha katı standartlara mı yöneliyorsunuz? Frontend'çi arkadaşlar, siz hangi response yapısını işlemeyi daha çok seviyorsunuz? Yorumlarda deneyimlerinizi paylaşın, tartışalım!
Neden HATEOAS Değil de JSON:API?HATEOAS, gerçekten de "ideal" REST'in son adımı. Her kaynağa ait işlemler için link'ler döndürüyor. Ancak, özellikle karmaşık ilişkili verilerde (örneğin, bir kullanıcının yazıları, yorumları, beğenileri) response'u okunması ve parse edilmesi zor bir hale getirebiliyordu. Ayrıca, frontend tarafında bu dinamik link'leri işleyecek generic bir client yazmak, projenin ilk aşamalarında büyük bir overhead'ti. JSON:API ise kesin kuralları, tutarlı yapısı ve include parametresi gibi özellikleriyle hem backend geliştiricisine hem de frontend geliştiricisine net bir yol haritası çiziyor.
Temel Yapıyı Kurmak (Laravel Örneği)Implementasyona Laravel üzerinden devam ettim. İlk iş, harika bir paket olan laravel-json-api/laravel paketini projeye eklemek oldu. Bu paket, spesifikasyonu büyük ölçüde otomatik olarak karşılıyor.
Kurulumdan sonra, ilk kaynak şemamızı oluşturalım. Diyelim ki bir Post modelimiz var.
PHP:
// app/JsonApi/V1/Posts/PostSchema.php
namespace App\JsonApi\V1\Posts;
use App\Models\Post;
use LaravelJsonApi\Core\Schema\Schema;
class PostSchema extends Schema
{
public static string $model = Post::class;
public function fields(): array
{
return [
ID::make(),
Str::make('title'),
Str::make('content'),
DateTime::make('createdAt')->sortable(),
BelongsTo::make('author')->type('users'),
HasMany::make('comments'),
];
}
public function filters(): array
{
return [
WhereIdIn::make($this),
Where::make('title'),
];
}
public function includePaths(): array
{
return [
'author',
'comments',
'comments.user' // İlişkileri iç içe include edebiliriz!
];
}
}Gördüğünüz gibi, modelimizin alanlarını, filtrelerini ve en önemlisi includePaths ile hangi ilişkilerin tek istekte getirilebileceğini tanımladık. Bu, N+1 sorgu problemini önlemek için çok kritik.
Frontend'te Hayat Nasıl Kolaylaştı?Backend'i bu şekilde ayarladıktan sonra, frontend (Vue.js) tarafında işler inanılmaz derecede standartlaştı. Artık tüm endpoint'ler tutarlı bir yapıda yanıt veriyor. İşte tipik bir get isteği ve response'u:
İstek: `GET /api/v1/posts/123?include=author,comments.user`
JavaScript:
// Response yapısı
{
"data": {
"type": "posts",
"id": "123",
"attributes": {
"title": "JSON:API Harika!",
"content": "Bu standart hayatımı kurtardı...",
"createdAt": "2023-10-05T10:00:00.000Z"
},
"relationships": {
"author": {
"data": { "type": "users", "id": "456" }
},
"comments": {
"data": [
{ "type": "comments", "id": "789" }
]
}
},
"links": {
"self": "https://api.ornek.com/posts/123"
}
},
"included": [
{
"type": "users",
"id": "456",
"attributes": {
"name": "Bingün",
"email": "bingun@ornek.com"
}
},
{
"type": "comments",
"id": "789",
"attributes": {
"body": "Katılıyorum!"
},
"relationships": {
"user": {
"data": { "type": "users", "id": "999" }
}
}
},
{
"type": "users",
"id": "999",
"attributes": {
"name": "Ziyaretçi",
"email": "ziyaretci@ornek.com"
}
}
]
}Bu yapının en güzel tarafı, included dizisi. Tek bir istekle ana post'u, yazarını, yorumları ve hatta yorum sahiplerini bile aldık. Frontend'te state yönetimi ve cache'leme işlemleri bu standart yapı sayesinde çok daha öngörülebilir hale geldi.
Sonuç ve DüşüncelerimJSON:API, özellikle orta ve büyük ölçekli projelerde takım içindeki iletişimi ve geliştirme hızını inanılmaz artırdı. HATEOAS'ın esnekliğinden ödün verdiğiniz doğru, ancak karşılığında muazzam bir tutarlılık ve geliştirici deneyimi (DX) kazanıyorsunuz. Spesifikasyonun sorting, filtering, pagination gibi konuları da standartlaştırması, API dokümantasyon yükünü de azaltıyor.
Siz backend geliştiriciler, REST API'lerinizde HATEOAS mı kullanıyorsunuz yoksa JSON:API veya GraphQL gibi daha katı standartlara mı yöneliyorsunuz? Frontend'çi arkadaşlar, siz hangi response yapısını işlemeyi daha çok seviyorsunuz? Yorumlarda deneyimlerinizi paylaşın, tartışalım!