REST API design 2026: versioning, errors, and compatibility

[Aior]

REST hâlâ güncel mi?​

GraphQL, gRPC, WebSocket gibi alternatifler 5 yıl öncesine göre çok daha yaygın olsa da REST API tasarımı 2026'da hâlâ kurumsal entegrasyonun ortak dili. AIOR'da müşteri taraflı API'lerin %80'i REST. Sebep basit: tooling olgun, dokümantasyon standartları geniş kabul görmüş, debugging araçları (curl, Postman, browser devtools) evrensel.

REST'in karşıt görüşleri haklı bir gerçeklik üzerine duruyor: kötü tasarlanmış REST API'ları frontend için ağır maliyet üretiyor. Ama bu REST'in kendi sorunu değil, tasarım disiplini eksikliğinin sorunu.

Resource modelleme — temel hatalar​

AIOR'da müşteri API'larını gözden geçirirken en sık görülen tasarım hataları:

• RPC endpoint'leri — `/api/sendEmail`, `/api/updateUserStatus` gibi action-based URL'ler REST değil; sadece gizli RPC. Resource kaynaklı düşünün: `POST /emails`, `PATCH /users/{id}/status`.
• Çok seviyeli nesting — `/users/{id}/orders/{oid}/items/{iid}/options/{oid}` gibi 5 seviye derin URL'ler okunamaz. 2 seviye yeterli; gerisi query parametresi.
• Plural vs singular karmaşası — bir endpoint `/users`, başka `/order` olmamalı. Tutarlılık tek doğru, plural tercih ediyoruz.
• ID semantiği — auto-increment integer ID'ler enumeration saldırılarına açık. UUID v7 (zamansal sıralı) AIOR varsayılanımız.

HTTP durum kodları gerçek anlamıyla kullanılmalı​

2026'da hâlâ "200 OK { success: false }" yanıt veren API'lar görüyoruz. Bu yanlış. Doğru HTTP semantik:

• 200 OK — başarılı GET/PUT/PATCH
• 201 Created — POST sonrası yeni kaynak; `Location` header dahil
• 204 No Content — DELETE veya body içermeyen başarı
• 400 Bad Request — istek formatı bozuk
• 401 Unauthorized — kimlik doğrulama gerekli
• 403 Forbidden — kimlik doğrulandı ama erişim yok
• 404 Not Found — kaynak yok
• 409 Conflict — durum çakışması (örn. zaten var olan kayıt)
• 422 Unprocessable Entity — validation hatası
• 429 Too Many Requests — rate limit
• 500-503 — server tarafı, ayırt edilmeli

Hata yanıtlarının yapısı​

RFC 7807 (Problem Details for HTTP APIs) artık geniş kabul. AIOR olarak tüm API hatalarını bu formatta üretiyoruz:

{
  "type": "https://api.aior.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "The 'email' field must be a valid email address.",
  "instance": "/users/abc123",
  "errors": [
    {"field": "email", "code": "invalid_format"}
  ]
}

Bu yapı hata kataloğunu standartlaştırıyor; frontend her hata yanıtını aynı kalıpla parse edebiliyor.

Versiyonlama yaklaşımı​

Üç temel yöntem var, AIOR olarak URL versiyonlamayı tercih ediyoruz:

• URL — `/v1/users`, `/v2/users`. Cache-friendly, debug kolay.
• Header — `Accept: application/vnd.aior.v2+json`. Daha "purist" ama curl/Postman'de gizli.
• Query param — `?version=2`. URL kirletir; önermez.

Eski sürümleri kapatmak için 6 ay önceden bildirim, 12 ay paralel destek standardımız.

Rate limiting ve idempotency​

• Her POST/PUT/PATCH/DELETE endpoint'i idempotency key kabul etmeli (`Idempotency-Key` header). Müşterinin retry yapması veriyi bozmamalı.
• Rate limit response'larında `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` header'ları zorunlu.
• Rate limit aşılırsa 429 ile birlikte `Retry-After` header.

Dokümantasyon​

OpenAPI 3.1 spesifikasyon kod ile birlikte yaşar; dokümantasyon kodun yansıması olmalıdır. AIOR'da Swagger UI veya Redoc ile interaktif dokümantasyon paylaşıyoruz. SDK üretimi (Python, Go, TypeScript) OpenAPI Generator ile otomatikleştiriliyor.

Her endpoint'in dokümantasyonunda örnek istek/yanıt ve olası hata yanıtları yer almalı. "TODO: docs" commit'leri AIOR projelerinde merge edilmez.

Pagination ve filtering​

Liste endpoint'lerinde offset-based pagination (`?page=2&per_page=20`) küçük veri setleri için iyi ama büyük setlerde performans kötü. Cursor-based pagination (`?cursor=eyJpZCI6MTAwfQ&limit=20`) AIOR'ın büyük veri seti API'leri için standardı. Filtering için RFC compliant query string yaklaşımı: `?filter[status]=active&filter[created_after]=2026-01-01`. Karmaşık filter ihtiyacı varsa POST /search endpoint'i ile JSON body kullanılır.

Güvenlik katmanları​

API güvenliği sadece kimlik doğrulama değil. AIOR olarak müşteri API'lerinde standart kabul ettiğimiz katmanlar: TLS 1.3 zorunlu, JWT veya OAuth 2.0 bearer token, scope-based authorization, audit log her endpoint için, CORS sıkı yapılandırma, content-type validation, request size limit, SQL injection için ORM kullanımı veya parametrize sorgu, XSS için output escaping (response JSON'unda HTML entity encoding gerekirse).

Sonuç​

REST API tasarımı 2026'da hâlâ canlı bir disiplin. İyi tasarlanmış REST API'leri yıllar boyu evrilir, ekipler arası iletişimi sadeleştirir, dış entegrasyonlar için pürüzsüz arayüz sunar. AIOR olarak her müşteri API'sini OpenAPI dokümantasyonu, Problem Details hata formatı ve idempotency desteği ile teslim ediyoruz. Sizin tarafınızda REST API tasarımında en sık karşılaştığınız problem ne — versiyonlama mı, hata kataloğu mu, yoksa pagination mı?

Is REST still current?​

GraphQL, gRPC, WebSocket and similar are far more common than five years ago, but REST API design in 2026 is still the lingua franca of enterprise integration. 80% of customer-facing APIs at AIOR are REST. The reasons are simple: mature tooling, widely accepted documentation standards, universal debugging tools (curl, Postman, browser devtools).

REST's critics stand on a real point: badly designed REST APIs cost the frontend dearly. But that isn't REST's fault — it's missing design discipline.

Resource modelling — common mistakes​

The most frequent design issues we see when reviewing customer APIs at AIOR:

• RPC endpoints — `/api/sendEmail`, `/api/updateUserStatus` aren't REST; they're disguised RPC. Think in resources: `POST /emails`, `PATCH /users/{id}/status`.
• Excessive nesting — `/users/{id}/orders/{oid}/items/{iid}/options/{oid}` is unreadable. Two levels deep is enough; the rest belongs in query params.
• Plural vs singular mix-up — one endpoint at `/users`, another at `/order`. Consistency is the only right answer; we prefer plural.
• ID semantics — auto-increment integer IDs are open to enumeration attacks. UUID v7 (time-sortable) is the AIOR default.

HTTP status codes used for their real meaning​

In 2026 we still see APIs return "200 OK { success: false }". That's wrong. Correct HTTP semantics:

• 200 OK — successful GET/PUT/PATCH
• 201 Created — POST that created a resource; include a `Location` header
• 204 No Content — DELETE or success with no body
• 400 Bad Request — malformed request
• 401 Unauthorized — authentication required
• 403 Forbidden — authenticated but not allowed
• 404 Not Found
• 409 Conflict — state conflict (e.g. record already exists)
• 422 Unprocessable Entity — validation failure
• 429 Too Many Requests — rate limit
• 500-503 — server-side, distinguish appropriately

The shape of error responses​

RFC 7807 (Problem Details for HTTP APIs) is now widely accepted. AIOR returns all API errors in this shape:

{
  "type": "https://api.aior.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "The 'email' field must be a valid email address.",
  "instance": "/users/abc123",
  "errors": [
    {"field": "email", "code": "invalid_format"}
  ]
}

This standardises the error catalogue; frontends can parse every error with one shape.

Versioning approach​

Three basic methods, we prefer URL versioning:

• URL — `/v1/users`, `/v2/users`. Cache-friendly, easy to debug.
• Header — `Accept: application/vnd.aior.v2+json`. More "purist" but hidden in curl/Postman.
• Query param — `?version=2`. Pollutes the URL; we don't recommend it.

To deprecate an old version: 6 months' advance notice, 12 months' parallel support is our standard.

Rate limiting and idempotency​

• Every POST/PUT/PATCH/DELETE endpoint must accept an idempotency key (`Idempotency-Key` header). A customer retry must not corrupt data.
• Rate limit responses must include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
• On rate-limit exceed, return 429 with `Retry-After`.

Documentation​

OpenAPI 3.1 spec lives with the code; documentation must be a reflection of the code. AIOR ships interactive docs via Swagger UI or Redoc. SDK generation (Python, Go, TypeScript) via OpenAPI Generator.

Every endpoint's documentation must include sample request/response and likely error responses. "TODO: docs" commits don't merge on AIOR projects.

Pagination and filtering​

Offset-based pagination (`?page=2&per_page=20`) is fine for small datasets but degrades on large sets. Cursor-based pagination (`?cursor=eyJpZCI6MTAwfQ&limit=20`) is the AIOR standard for large-dataset APIs. For filtering, an RFC-compliant query string: `?filter[status]=active&filter[created_after]=2026-01-01`. For complex filtering needs, use a POST /search endpoint with a JSON body.

Security layers​

API security is more than authentication. AIOR's standard on customer APIs: TLS 1.3 mandatory, JWT or OAuth 2.0 bearer tokens, scope-based authorisation, audit log per endpoint, strict CORS, content-type validation, request size limits, SQL injection prevention through ORM or parameterised queries, XSS prevention through output escaping (HTML entity encoding in response JSON where needed).

Bottom line​

REST API design in 2026 is still a living discipline. Well-designed REST APIs evolve for years, simplify cross-team communication, and provide a smooth interface for external integration. AIOR ships every customer API with OpenAPI docs, Problem Details error format, and idempotency support. What's the most frequent pain in REST API design on your side — versioning, error catalogue, or pagination?