API stilinin seçimi
Bir API tasarlamak demek sadece endpoint yazmak değil; üç ila beş yıl boyunca yaşayacak bir sözleşme yapmak demektir. AIOR olarak müşteri projelerinde API stilini seçerken üç ana kriter değerlendiriyoruz: tüketici tipi (internal mi public mi), data shape karakteri (sabit mi dinamik mi), performans gerekliliği. Doğru cevap her zaman REST değil; ama %70 oranında REST.REST — varsayılan tercih ve nedeni
REST 2026'da hâlâ kurumsal entegrasyonun ortak dili. Olgun tooling (curl, Postman, Swagger UI), evrensel debugging araçları, geniş kabul. AIOR projelerinin %75'i REST API kullanıyor.İyi REST için disiplin:
- Resource-based URL'ler (`/orders/123`, `/users/456/posts`).
- HTTP method'ları doğru semantik (GET idempotent, POST yeni kaynak, PATCH partial update, DELETE).
- Status code'lar gerçek anlamıyla (200, 201, 204, 400, 401, 403, 404, 409, 422, 429).
- Versiyonlama — URL path (`/v1/`, `/v2/`).
- Pagination — cursor-based büyük setler için.
- Filtering — query string standardı.
- Hata formatı — RFC 7807 Problem Details.
GraphQL — nereye uyar?
GraphQL'in güçlü yanları: client over-fetching ve under-fetching probleminin çözümü, tek endpoint ile multiple resource fetch, schema-driven development.AIOR'da GraphQL'i tercih ettiğimiz senaryolar:
- Mobile uygulama + web client'ı aynı API'ya bağlanıyor, farklı data ihtiyaçları var.
- Frontend ekibi sık değişen UI gereksinimleri ile çalışıyor; her UI değişikliğinde backend endpoint değiştirilmek istenmiyor.
- Complex nested data fetching gerekli — n+1 problem REST'te dataloader gerektiriyor.
- Internal developer portal — multiple service'in tek API üzerinden açık olması istenir.
Ödünleşmeler: caching karmaşık (CDN-level cache REST kadar etkili değil), HTTP debugging araçları sınırlı (Apollo DevTools yardımcı), GraphQL injection güvenlik konuları (depth limit, complexity limit zorunlu).
AIOR olarak müşteri API'lerinin %15-20'sini GraphQL ile teslim ediyoruz. Apollo Server (Node.js) veya graphql-php (PHP) en sık kullandığımız implementasyonlar.
gRPC — yüksek performans senaryolarda
gRPC, HTTP/2 üzerine Protocol Buffers ile binary serialization. AIOR'da gRPC'yi tercih ettiğimiz durumlar:- Service-to-service iletişim (internal microservices).
- Yüksek throughput, düşük latency gereksinimi.
- Polyglot stack — farklı dillerde servis paylaşımlı kontrat.
- Streaming (server-streaming, client-streaming, bi-directional).
Ödünleşmeler: browser native desteği yok (gRPC-Web bridge gerekir), curl ile debugging zor, HTTP tooling sınırlı.
AIOR projelerinde gRPC'yi public API olarak değil, internal service mesh içinde kullanıyoruz.
Authentication ve authorization
API güvenliği kritik. AIOR projelerinde standart yaklaşımlar:- API key — basit, machine-to-machine, low-security kullanımlar.
- JWT (Bearer token) — stateless authentication, kısa ömürlü.
- OAuth 2.0 + OIDC — third-party access delegation.
- mTLS — service-to-service, sertifika tabanlı.
Authorization için RBAC (Role-Based Access Control) veya ABAC (Attribute-Based Access Control) — kompleks domain'ler için ABAC daha esnek.
Rate limiting ve quota
Her API endpoint için rate limit zorunlu. AIOR'da uyguladığımız desen: tier-based quotas (free/paid/enterprise), token bucket algorithm, Redis-backed counter. Rate limit aşıldığında 429 Too Many Requests + Retry-After header.Idempotency
POST/PUT/PATCH/DELETE endpoint'leri için idempotency key kabul etmek 2026'da modern standart. `Idempotency-Key: uuid` header ile retry güvenli. Network kesintilerinde client retry yapabilir, duplicate işlem oluşmaz.Dokümantasyon — kod ile yaşar
OpenAPI 3.1 spec REST API'ler için, GraphQL SDL GraphQL API'ler için, Protocol Buffers gRPC için — her birinde dokümantasyon kod ile birlikte sürümlenir. AIOR projelerinde Swagger UI veya Redoc ile interaktif dokümantasyon paylaşılır.Sürüm yönetimi
API'lar yıllar boyu yaşar. AIOR'ın versiyonlama disiplini:- Major version değişiklikleri URL'de (`/v1/`, `/v2/`).
- Breaking change duyurusu 6 ay önceden.
- Eski sürüm 12 ay paralel destek.
- Deprecation header (Sunset, Deprecation) ile client'ı uyar.
Sonuç
API stili seçimi proje karakterine göre yapılır, moda göre değil. AIOR olarak REST'i varsayılan, GraphQL'i client-specific data ihtiyacında, gRPC'yi internal service iletişiminde tercih ediyoruz. Hangisini seçersek seçelim, güvenlik (auth, rate limit, idempotency) ve dokümantasyon (OpenAPI, SDL) pazarlık edilmez. Sizin tarafınızda API stilini seçerken en sık karşılaştığınız zorluk ne — sürüm yönetimi, performans, yoksa client çeşitliliği mi?Choosing the API style
Designing an API isn't just writing endpoints; it's making a contract that will live for three to five years. When AIOR picks an API style on customer projects, we evaluate three criteria: consumer type (internal vs public), data shape (fixed vs dynamic), and performance requirement. The right answer isn't always REST — but it's REST about 70% of the time.REST — the default and why
REST is still the lingua franca of enterprise integration in 2026. Mature tooling (curl, Postman, Swagger UI), universal debugging tools, broad acceptance. 75% of AIOR projects use REST APIs.Discipline for good REST:
- Resource-based URLs (`/orders/123`, `/users/456/posts`).
- Correct HTTP method semantics (GET idempotent, POST creates, PATCH partial update, DELETE).
- Status codes with their true meaning (200, 201, 204, 400, 401, 403, 404, 409, 422, 429).
- Versioning — URL path (`/v1/`, `/v2/`).
- Pagination — cursor-based for large sets.
- Filtering — query string standard.
- Error format — RFC 7807 Problem Details.
GraphQL — where does it fit?
GraphQL's strengths: solves client over-fetching and under-fetching, single endpoint with multi-resource fetch, schema-driven development.When AIOR picks GraphQL:
- Mobile app + web client hitting the same API with different data needs.
- A frontend team working with frequently changing UI requirements; they don't want to change backend endpoints every time.
- Complex nested data fetching is required — n+1 problem in REST requires dataloader.
- Internal developer portal — multiple services exposed through one API.
Trade-offs: caching is complex (CDN-level cache isn't as effective as REST), HTTP debugging tools are limited (Apollo DevTools helps), GraphQL injection security issues (depth limit, complexity limit mandatory).
AIOR delivers 15–20% of customer APIs in GraphQL. Apollo Server (Node.js) or graphql-php (PHP) are our most-used implementations.
gRPC — in high-performance scenarios
gRPC: HTTP/2 with Protocol Buffers and binary serialisation. Cases where AIOR picks gRPC:- Service-to-service communication (internal microservices).
- High throughput, low latency requirements.
- Polyglot stack — services in different languages sharing a contract.
- Streaming (server-streaming, client-streaming, bi-directional).
Trade-offs: no native browser support (gRPC-Web bridge needed), hard to debug with curl, limited HTTP tooling.
AIOR uses gRPC inside the internal service mesh, not as a public API.
Authentication and authorisation
API security is critical. Standard approaches on AIOR projects:- API key — simple, machine-to-machine, low-security use.
- JWT (Bearer token) — stateless authentication, short-lived.
- OAuth 2.0 + OIDC — third-party access delegation.
- mTLS — service-to-service, certificate-based.
For authorisation, RBAC (Role-Based Access Control) or ABAC (Attribute-Based Access Control) — ABAC is more flexible for complex domains.
Rate limiting and quota
Rate limit is mandatory on every API endpoint. The pattern we use at AIOR: tier-based quotas (free/paid/enterprise), token bucket algorithm, Redis-backed counter. On rate-limit exceed, 429 Too Many Requests + Retry-After header.Idempotency
Accepting an idempotency key on POST/PUT/PATCH/DELETE endpoints is the modern standard in 2026. `Idempotency-Key: uuid` header makes retries safe. On network failures, clients can retry without producing duplicate operations.Documentation — lives with the code
OpenAPI 3.1 spec for REST APIs, GraphQL SDL for GraphQL APIs, Protocol Buffers for gRPC — documentation is versioned with code in each. AIOR shares interactive documentation via Swagger UI or Redoc.Version management
APIs live for years. AIOR's versioning discipline:- Major version changes in URL (`/v1/`, `/v2/`).
- Breaking change announcements 6 months in advance.
- Old version supported in parallel for 12 months.
- Deprecation headers (Sunset, Deprecation) warn clients.
