api_design

•

43126 months ago

API tasarımı, GraphQL schema, OpenAPI spec, versioning. ⚠️ Tasarım aşaması için kullan. Uygulama/security için → backend-api.

Quick Install

npxskills add vuralserhat86/antigravity-agentic-skills--skill api_design

Instructions

🔌 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

Loading…

Related Skills

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,360

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,309

1password

Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.

365,915

himalaya

CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).

365,885