API Design Vuralserhat86 Antigravity Agentic

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