vuralserhat86/skills/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

| Code | Kullanım | |------|----------| | 200/201/204 | OK/Created/No Content | | 400/401/403/404/422 | Bad/Unauth/Forbidden/NotFound/Validation | | 500/503 | Server Error/Unavailable |

---

📐 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

| Yöntem | Örnek | Öneri | |--------|-------|-------| | URL (önerilen) | /api/v1/users | ✅ En yaygın | | Header | Accept: ...version=1 | Opsiyonel | | Query | ?version=1 | Kaçın |

---

📊 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ı

| Aşama | Doğrulama | |-------|-----------| | 1 | OpenAPI spec onaylandı (lint geçerli) | | 2 | Kod ve Spec tipleri senkronize (codegen) | | 3 | Contract testleri geçiyor | | 4 | Dokümantasyon canlı ve güncel |