
API (Uygulama Programlama Arayüzü), bir servis sağlayıcı ile tüketicileri arasındaki bir sözleşmedir. İyi tasarlanmış bir API sezgisel, tutarlı ve kullanımı kolaydır. Kötü tasarlanmış bir API, geliştiricilerin hayal kırıklığına uğramasına, artan destek yüküne, güvenlik açıklarına ve maliyetli değişikliklere yol açar.
API (Uygulama Programlama Arayüzü), bir servis sağlayıcı ile tüketicileri arasındaki bir sözleşmedir. İyi tasarlanmış bir API sezgisel, tutarlı ve kullanımı kolaydır. Kötü tasarlanmış bir API, geliştiricilerin hayal kırıklığına uğramasına, artan destek yüküne, güvenlik açıklarına ve maliyetli değişikliklere yol açar.
API'ler ürünlerdir; bunları kullanıcı arayüzleriyle aynı özenle tasarlayın. İster REST, GraphQL ister gRPC oluşturuyor olun, iyi API tasarımının ilkeleri tutarlı kalır.
Kaynaklar sisteminizdeki temel varlıklardır. Bunları fiillerle değil isimlerle adlandırın:
✅ GET /users — List users
✅ GET /users/123 — Get user by ID
✅ POST /users — Create user
✅ PATCH /users/123 — Partially update user
✅ PUT /users/123 — Replace user
✅ DELETE /users/123 — Delete user
❌ GET /getUser — Verb in URL
❌ POST /createUser — Verb in URL
❌ POST /users/create — Verb in URL path
❌ GET /users?action=delete — Action as query parameter
| Yöntem | Amaç | İdempotent | Güvenli | Vücut |
|---|---|---|---|---|
| ALIN | Bir kaynağı alın | Evet | Evet | Hayır |
| GÖNDERİM | Kaynak oluştur | Hayır | Hayır | Evet |
| koy | Tam değiştirme | Evet | Hayır | Evet |
| YAMA | Kısmi güncelleme | Hayır | Hayır | Evet |
| SİL | Kaynağı kaldırma | Evet | Hayır | İsteğe bağlı |
Idempotent: Birden fazla özdeş istek, tek bir istekle aynı sonucu üretir.
Güvenli: Yan etkisi yoktur — önbelleğe alınabilir ve güvenli bir şekilde tekrarlanabilir.
naming_rules:
- "Use plural nouns: /users, /orders, /products"
- "Use kebab-case for multi-word: /order-items, /shipping-addresses"
- "Use lowercase throughout"
- "Nest resources logically: /users/123/orders"
- "Avoid deep nesting (max 2-3 levels)"
- "Use query parameters for filtering, sorting, pagination"
Yuvalama örneği:
/users/123/orders — Orders belonging to user 123
/users/123/orders/456 — Specific order
/users/123/orders/456/items — Items in that order (okay)
/users/123/orders/456/items/789/details (too deep!)
Son değişiklikler sürümü artırmalıdır:
URI sürümü oluşturma (en yaygın):
https://api.example.com/v1/users
https://api.example.com/v2/users
Başlık sürümü oluşturma:
Accept: application/vnd.example.v1+json
Aşağıdaki durumlar dışında aynı sürümdeki geriye dönük uyumluluğu asla bozmayın:
2xx Success:
200 OK: Generic success (GET, PATCH)
201 Created: Resource created (POST)
204 No Content: Success, no response body (DELETE)
3xx Redirection:
301 Moved Permanently
304 Not Modified (caching)
4xx Client Error:
400 Bad Request: Malformed request, validation error
401 Unauthorized: Missing or invalid authentication
403 Forbidden: Authenticated but not authorized
404 Not Found: Resource does not exist
405 Method Not Allowed: Wrong HTTP method
409 Conflict: Resource state conflict (duplicate, version mismatch)
422 Unprocessable Entity: Semantic validation failure
429 Too Many Requests: Rate limit exceeded
5xx Server Error:
500 Internal Server Error: Unexpected server failure
502 Bad Gateway: Upstream service failed
503 Service Unavailable: Temporary overload/maintenance
504 Gateway Timeout: Upstream service timed out
{
"data": {
"id": "user_123",
"email": "john@example.com",
"name": "John Doe",
"created_at": "2024-01-15T10:30:00Z"
},
"meta": {
"request_id": "req_abc123",
"timestamp": "2024-01-15T10:30:00Z"
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The request body contains validation errors",
"details": [
{
"field": "email",
"message": "Email is required",
"code": "REQUIRED_FIELD"
},
{
"field": "age",
"message": "Age must be between 18 and 120",
"code": "INVALID_VALUE",
"constraints": {
"minimum": 18,
"maximum": 120
}
}
]
}
}
GET /users?page=2&per_page=20&sort=created_at:desc
{
"data": [ ... ],
"meta": {
"page": 2,
"per_page": 20,
"total": 100,
"total_pages": 5,
"count": 20
},
"links": {
"first": "/users?page=1&per_page=20",
"prev": "/users?page=1&per_page=20",
"next": "/users?page=3&per_page=20",
"last": "/users?page=5&per_page=20"
}
}
İmleç tabanlı sayfalandırma (büyük veri kümeleri için önerilir):
GET /users?cursor=eyJpZCI6IDUwMH0=&limit=20
{
"data": [ ... ],
"meta": {
"next_cursor": "eyJpZCI6IDUyMH0=",
"has_more": true
}
}
// Filtering
GET /users?role=admin&status=active
GET /orders?created_at[gte]=2024-01-01&total[gt]=100
// Sorting
GET /users?sort=name:asc,created_at:desc
// Searching
GET /users?search=john
// Field selection (sparse fields)
GET /users/123?fields=id,name,email
// PUT — Full replacement (requires all fields)
PUT /users/123
{
"email": "newemail@example.com",
"name": "John Updated",
"age": 31
}
// PATCH — Partial update (only send changed fields)
PATCH /users/123
{
"email": "newemail@example.com"
}
Önerilen: OAuth 2.0 + OpenID Connect
POST /oauth/token
Content-Type: application/json
{
"grant_type": "client_credentials",
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"scope": "read write"
}
Response:
{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read write"
}
GET /api/users
Authorization: Bearer eyJhbGciOi...
// Header
{
"alg": "RS256",
"typ": "JWT"
}
// Payload
{
"sub": "user_123",
"iss": "auth.example.com",
"iat": 1705312200,
"exp": 1705315800,
"scope": "read:users write:users",
"roles": ["admin"]
}
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705315800
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Content-Type: application/json
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Try again in 3600 seconds.",
"retry_after": 3600
}
}
// Zod validation schema for API input
import { z } from 'zod';
const createUserSchema = z.object({
email: z.string().email('Invalid email format'),
name: z.string().min(1, 'Name is required').max(100),
age: z.number().int().min(18).max(120).optional(),
role: z.enum(['user', 'admin', 'moderator']).default('user'),
tags: z.array(z.string()).max(10).optional(),
});
// Validation middleware
function validate(schema: ZodSchema) {
return (req, res, next) => {
const result = schema.safeParse(req.body);
if (!result.success) {
return res.status(422).json({
error: {
code: 'VALIDATION_ERROR',
message: 'Validation failed',
details: result.error.issues.map(i => ({
field: i.path.join('.'),
message: i.message
}))
}
});
}
req.validatedBody = result.data;
next();
};
}
// CORS configuration
const corsOptions = {
origin: [
'https://app.example.com',
'https://admin.example.com',
],
methods: ['GET', 'POST', 'PATCH', 'DELETE'],
allowedHeaders: ['Content-Type', 'Authorization'],
exposedHeaders: ['X-RateLimit-Remaining'],
credentials: true,
maxAge: 86400 // Preflight cache (24 hours)
};
app.use(cors(corsOptions));
openapi: 3.0.3
info:
title: User Management API
version: 2.0.0
description: API for managing users in the system
contact:
email: api-support@example.com
servers:
- url: https://api.example.com/v2
description: Production server
paths:
/users:
get:
summary: List all users
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: per_page
in: query
schema:
type: integer
default: 20
maximum: 100
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
meta:
$ref: '#/components/schemas/PaginationMeta'
post:
summary: Create a new user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'422':
description: Validation error
components:
schemas:
User:
type: object
properties:
id:
type: string
email:
type: string
format: email
name:
type: string
created_at:
type: string
format: date-time
# Serve Swagger UI for API documentation
npm install -g swagger-ui-express
# Visit: https://api.example.com/docs
// Pact consumer-driven contract test
const { Pact } = require('@pact-foundation/pact');
describe('User API contract', () => {
const provider = new Pact({
consumer: 'Frontend App',
provider: 'User Service',
port: 1234,
});
beforeAll(() => provider.setup());
describe('GET /users/123', () => {
beforeAll(() => {
return provider.addInteraction({
state: 'User 123 exists',
uponReceiving: 'a request for user 123',
withRequest: {
method: 'GET',
path: '/users/123',
headers: { Authorization: 'Bearer valid-token' }
},
willRespondWith: {
status: 200,
headers: { 'Content-Type': 'application/json' },
body: {
data: {
id: '123',
email: 'user@example.com',
name: 'Test User'
}
}
}
});
});
it('returns the user', async () => {
const response = await fetch('http://localhost:1234/users/123', {
headers: { Authorization: 'Bearer valid-token' }
});
expect(response.status).toBe(200);
});
afterEach(() => provider.verify());
});
afterAll(() => provider.finalize());
});
| Görünüş | DİNLENME | GrafikQL |
|---|---|---|
| Veri getiriliyor | Çoklu uç noktalar, sabit yanıt | Tek uç nokta, müşteri tanımlı |
| Aşırı getiriliyor | Gerekenden daha fazla veri döndürebilir | Tam olarak ihtiyacınız olanı isteyin |
| Yeterince getirilmiyor | Birden fazla istek gerekebilir (N+1) | İç içe geçmiş veriler için tek istek |
| Önbelleğe alma | Yerleşik (HTTP önbelleğe alma, CDN) | Özel (Apollo önbelleği, Aktarma) |
| Aletleme | Yetişkinlere yönelik (kıvırma, Postacı, tarayıcılar) | Büyüyor (GraphiQL, Apollo DevTools) |
| Öğrenme eğrisi | Düşük | Orta |
| Sürüm oluşturma | URI sürümü oluşturma | Alan ekleyin, eskileri kullanımdan kaldırın |
| Dosya yükleme | Yerel (çok parçalı) | Özel kullanım gerektirir |
| Gerçek zamanlı | WebSocket, SSE | Abonelikler |
version_policy:
- v1: Initial release (stable, deprecated)
- v2: Current version (active development)
- v3: Planned (future)
deprecation:
notice_period: 6 months
communication: email, API response header
sunset_header: true # Deprecation: true
transition:
new_features: v2 only
bug fixes: v1 critical only
migrations: provide migration guide
GET /v1/users/123
Sunset: Sat, 30 Nov 2024 00:00:00 GMT
Deprecation: true
Link: </v2/users/123>; rel="successor-version"
İyi API tasarımı şu ilkeleri takip eder:
API bir üründür. Tasarımına yatırım yapın, ayrıntılı bir şekilde belgeleyin, dikkatlice sürümlendirin ve her önemli değişikliğe hak ettiği ciddiyetle yaklaşın.
Henüz onaylı yorum yok. Yeni yanıtlar moderasyon bekleyebilir.