Cursor로 API 구축하기: REST, GraphQL 및 FastAPI

견고한 API를 구축하려면 신중한 계획, 일관된 패턴, 철저한 테스트가 필요합니다. Cursor의 AI 기능은 엔드포인트 스캐폴딩부터 OpenAPI 문서 생성까지 API 개발의 모든 단계를 가속화할 수 있습니다. 이 가이드에서는 REST, GraphQL, FastAPI 워크플로우를 다룹니다.

사전 요구 사항

시작하기 전에 다음이 필요합니다:

• Pro 플랜이 포함된 Cursor 설치 (권장)
• Node.js 또는 Python 설치
• HTTP 개념 및 JSON에 대한 이해

REST API 개발

프로젝트 스캐폴딩

Cursor에게 완전한 REST API를 스캐폴드하도록 요청하세요:

Express.js로 다음을 포함하는 REST API를 생성해주세요:
- TypeScript
- src/routes/의 라우트 핸들러
- 로깅 및 오류 처리를 위한 미들웨어
- Zod를 사용한 입력 유효성 검사
- JWT 인증
- 속도 제한
- Swagger 문서화

Express.js 라우트 구조

// src/routes/users.ts
import { Router } from 'express';
import { z } from 'zod';
import { authenticate } from '../middleware/auth';
import { validate } from '../middleware/validate';

const router = Router();

const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2).max(100),
  password: z.string().min(8),
});

router.post(
  '/',
  authenticate,
  validate(createUserSchema),
  async (req, res, next) => {
    try {
      const user = await createUser(req.body);
      res.status(201).json({
        success: true,
        data: user,
      });
    } catch (error) {
      next(error);
    }
  }
);

router.get('/:id', authenticate, async (req, res, next) => {
  try {
    const user = await getUserById(req.params.id);
    if (!user) {
      return res.status(404).json({
        success: false,
        error: 'User not found',
      });
    }
    res.json({ success: true, data: user });
  } catch (error) {
    next(error);
  }
});

export default router;

통합 오류 처리

// src/middleware/errorHandler.ts
import { Request, Response, NextFunction } from 'express';

export class AppError extends Error {
  constructor(
    public statusCode: number,
    public message: string,
    public isOperational = true
  ) {
    super(message);
    Object.setPrototypeOf(this, AppError.prototype);
  }
}

export const errorHandler = (
  err: Error,
  req: Request,
  res: Response,
  next: NextFunction
) => {
  if (err instanceof AppError) {
    return res.status(err.statusCode).json({
      success: false,
      error: err.message,
    });
  }

  console.error('Unexpected error:', err);
  res.status(500).json({
    success: false,
    error: 'Internal server error',
  });
};

Cursor를 활용한 FastAPI 개발

FastAPI 엔드포인트 생성

# main.py
from fastapi import FastAPI, HTTPException, Depends, status
from fastapi.security import OAuth2PasswordBearer
from pydantic import BaseModel, EmailStr
from typing import List, Optional
import uvicorn

app = FastAPI(
    title="My API",
    description="A production-ready API built with FastAPI",
    version="1.0.0",
)

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

# Pydantic models
class UserCreate(BaseModel):
    email: EmailStr
    name: str
    password: str

class UserResponse(BaseModel):
    id: int
    email: str
    name: str

    class Config:
        from_attributes = True

# In-memory storage (replace with database)
users_db = {}
user_counter = 0

@app.post(
    "/users",
    response_model=UserResponse,
    status_code=status.HTTP_201_CREATED,
    tags=["users"],
)
async def create_user(user: UserCreate):
    global user_counter
    user_counter += 1
    new_user = {
        "id": user_counter,
        "email": user.email,
        "name": user.name,
    }
    users_db[user_counter] = new_user
    return new_user

@app.get(
    "/users/{user_id}",
    response_model=UserResponse,
    tags=["users"],
)
async def get_user(user_id: int):
    if user_id not in users_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="User not found",
        )
    return users_db[user_id]

@app.get("/users", response_model=List[UserResponse], tags=["users"])
async def list_users(
    skip: int = 0,
    limit: int = 100,
):
    return list(users_db.values())[skip : skip + limit]

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

의존성 주입

# dependencies.py
from fastapi import Depends, HTTPException, status
from sqlalchemy.orm import Session
from database import SessionLocal

async def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

async def get_current_user(token: str = Depends(oauth2_scheme)):
    user = verify_token(token)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid authentication",
        )
    return user

# Usage
@app.get("/items")
async def read_items(
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user),
):
    return db.query(Item).filter(Item.owner_id == current_user.id).all()

GraphQL API 개발

Apollo Server 설정

// src/schema.ts
import { gql } from 'apollo-server-express';

export const typeDefs = gql`
  type User {
    id: ID!
    email: String!
    name: String!
    posts: [Post!]!
  }

  type Post {
    id: ID!
    title: String!
    content: String!
    author: User!
  }

  type Query {
    users: [User!]!
    user(id: ID!): User
    posts: [Post!]!
    post(id: ID!): Post
  }

  type Mutation {
    createUser(email: String!, name: String!, password: String!): User!
    createPost(title: String!, content: String!, authorId: ID!): Post!
  }
`;

Cursor를 활용한 리졸버

// src/resolvers.ts
export const resolvers = {
  Query: {
    users: async (_, __, { dataSources }) => {
      return dataSources.userAPI.getAllUsers();
    },
    user: async (_, { id }, { dataSources }) => {
      return dataSources.userAPI.getUserById(id);
    },
  },
  User: {
    posts: async (parent, _, { dataSources }) => {
      return dataSources.postAPI.getPostsByAuthor(parent.id);
    },
  },
  Mutation: {
    createUser: async (_, args, { dataSources }) => {
      return dataSources.userAPI.createUser(args);
    },
  },
};

GraphQL 스키마 설계

Cursor를 사용하여 데이터베이스 스키마에서 GraphQL 스키마를 생성하세요. Prisma 스키마를 붙여넣고 해당 GraphQL 타입 정의를 요청하세요.

인증 및 권한 부여

JWT 구현

// src/utils/jwt.ts
import jwt from 'jsonwebtoken';
import bcrypt from 'bcrypt';

const JWT_SECRET = process.env.JWT_SECRET!;
const SALT_ROUNDS = 12;

export const hashPassword = async (password: string): Promise<string> => {
  return bcrypt.hash(password, SALT_ROUNDS);
};

export const comparePassword = async (
  password: string,
  hash: string
): Promise<boolean> => {
  return bcrypt.compare(password, hash);
};

export const generateToken = (payload: object): string => {
  return jwt.sign(payload, JWT_SECRET, { expiresIn: '24h' });
};

export const verifyToken = (token: string): any => {
  return jwt.verify(token, JWT_SECRET);
};

미들웨어 패턴

// src/middleware/rateLimit.ts
import rateLimit from 'express-rate-limit';

export const apiLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per windowMs
  message: {
    success: false,
    error: 'Too many requests, please try again later',
  },
  standardHeaders: true,
  legacyHeaders: false,
});

API 문서화

FastAPI의 OpenAPI

FastAPI는 자동으로 OpenAPI 문서를 생성합니다. 다음에서 접근:

• Swagger UI: /docs
• ReDoc: /redoc

Swagger가 포함된 Express.js

// src/config/swagger.ts
import swaggerJsdoc from 'swagger-jsdoc';

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
      description: 'API documentation',
    },
    servers: [
      {
        url: 'http://localhost:3000/api',
      },
    ],
  },
  apis: ['./src/routes/*.ts'],
};

export const specs = swaggerJsdoc(options);

API 테스트

통합 테스트 예시

// tests/users.test.ts
import request from 'supertest';
import app from '../src/app';

describe('Users API', () => {
  describe('POST /users', () => {
    it('should create a new user', async () => {
      const response = await request(app)
        .post('/users')
        .send({
          email: '[email protected]',
          name: 'Test User',
          password: 'securePassword123',
        })
        .expect(201);

      expect(response.body.success).toBe(true);
      expect(response.body.data.email).toBe('[email protected]');
    });

    it('should reject invalid email', async () => {
      await request(app)
        .post('/users')
        .send({
          email: 'invalid-email',
          name: 'Test',
          password: 'password',
        })
        .expect(400);
    });
  });
});

API 설계 모범 사례

사례	구현
버전 관리	URL에 /api/v1/ 접두사 사용
페이지네이션	{ data, meta: { page, limit, total } } 반환
필터링	쿼리 매개변수 사용: ?status=active&sort=created_at
오류 형식	일관된 { success: false, error: "message" }
속도 제한	공개 엔드포인트당 15분에 100회 요청
캐싱	ETag 헤더 및 Redis를 사용한 응답 캐싱

일반적인 API 패턴

리포지토리 패턴

// src/repositories/UserRepository.ts
export class UserRepository {
  async findById(id: string): Promise<User | null> {
    return prisma.user.findUnique({ where: { id } });
  }

  async findByEmail(email: string): Promise<User | null> {
    return prisma.user.findUnique({ where: { email } });
  }

  async create(data: CreateUserInput): Promise<User> {
    return prisma.user.create({ data });
  }

  async update(id: string, data: UpdateUserInput): Promise<User> {
    return prisma.user.update({ where: { id }, data });
  }

  async delete(id: string): Promise<void> {
    await prisma.user.delete({ where: { id } });
  }
}

환경 구성

# .env
NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://user:pass@localhost:5432/myapp
JWT_SECRET=your-secret-key
REDIS_URL=redis://localhost:6379
RATE_LIMIT_MAX=100

빠른 참고

작업	Cursor 프롬프트
CRUD 엔드포인트 생성	"Create CRUD endpoints for a Product resource with validation"
인증 추가	"Add JWT authentication middleware to all protected routes"
GraphQL 스키마 생성	"Generate GraphQL types from this Prisma schema"
테스트 작성	"Write integration tests for the user registration endpoint"
속도 제한 추가	"Add rate limiting to the API with different tiers for auth vs public"

관련 리소스

• Cursor 데이터베이스 개발 가이드
• Cursor Docker 개발 가이드
• Cursor 테스트 가이드

마지막 업데이트: 2025년 7월