🔌 API Design

🔌 API Design

RESTful ve GraphQL API tasarımı rehberi.

---

⚡ Quick Reference

HTTP Methods

GET(read) · POST(create) · PUT(full-update) · PATCH(partial) · DELETE

Status Codes

2xx Success · 4xx Client Error · 5xx Server Error

---

📐 Endpoint Design

Pattern: /​api/​v{n}/​{resource}/​{id?}/​{sub-resource?}

✅ GET  /​api/​v1/​users
✅ GET  /​api/​v1/​users/​{id}
✅ POST /​api/​v1/​users
❌ GET  /​api/​v1/​getUsers (verb kullanma!)

Query Params

?page=1&limit=20 · ?status=active · ?sort=createdAt&order=desc · ?fields=id,name

---

📦 Response Format

// Success
{ success: true, data: T, meta?: { page, total } }

// Error  
{ success: false, error: { code: string, message: string, details?: [] } }

---

🔄 Versioning

---

📊 GraphQL Essentials

type Query {
  user(id: ID!): User
  users(filter: Filter, pagination: Pagination): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): UserPayload!
}

N+1 Çözümü: DataLoader, Batch loading, Query complexity limiting

---

📝 OpenAPI Temel

openapi: 3.0.3
info: { title: API, version: 1.0.0 }
paths:
  /​users:
    get:
      responses:
        '200': { $ref: '#/​components/​schemas/​UserList' }

---

API Design v2.0 - Compact

🔄 Workflow

Kaynak: Best Practices for API-First Development

Aşama 1: Design Phase (Spec-First)

• Define Resources: Identify nouns (Users, Orders) and relationships.
• Draft OpenAPI/​Schema: Write openapi.yaml or schema.graphql BEFORE coding.
• Mocking: Use tools like Prism/​Stoplight to generate mock servers from spec.
• Review: Get stakeholder feedback on the mock API.

Aşama 2: Implementation

• Codegen: Generate TypeScript types/​interfaces from the spec.
• Business Logic: Implement controllers/​resolvers connecting to services.
• Validation: Ensure Zod/​Joi schemas match the OpenAPI spec.

Aşama 3: Testing & Security

• Contract Testing: Verify implementation matches spec (e.g., using Dredd/​Pact).
• Security Audit: Check Rate Limiting, AuthN/​AuthZ scopes.
• Error Handling: Verify standard error responses (RFC 7807).

Aşama 4: Documentation (Auto)

• Publish: Deploy Swagger UI / Redoc.
• Changelog: Document breaking changes if any (versioning strategy).

Kontrol Noktaları