REST API 만드는 법: 설계, 보안, 배포

REST API를 만들려면 앱이 관리하는 리소스(사용자, 주문, 예약 등)를 정하고, 각 리소스에 /orders, /orders/{id} 같은 URL을 부여한 다음, 동작에는 HTTP 메서드를 사용하세요. 읽기는 GET, 생성은 POST, 수정은 PATCH, 삭제는 DELETE입니다. 의미 있는 상태 코드와 함께 JSON을 반환하고, 모든 입력을 검증하고, 서버에서 인증과 레코드별 권한 확인을 요구하고, 목록은 페이지로 나누세요. 그다음 엔드포인트를 문서화하고 HTTPS 뒤에서 API를 배포하세요.

이 가이드는 설계 결정, 구체적인 경로 예시, AI 앱 빌더에 줄 프롬프트, 보안 구멍을 만드는 실수를 다룹니다. API가 낯설다면 먼저 API란 무엇인가부터 읽어 보세요.

REST API가 필요한 경우

• 웹 프런트엔드가 서버에 데이터를 저장하고 불러와야 할 때
• 모바일 앱, 파트너 또는 자동화 도구가 데이터에 접근해야 할 때
• 다른 서비스가 나에게 이벤트를 보낼 때 (웹훅)
• 프런트엔드 팀과 백엔드 팀이 작업을 나눠 할 때

REST가 가장 흔한 방식이지만 유일한 방식은 아닙니다. 하나의 유연한 쿼리 엔드포인트가 더 잘 맞는 경우는 REST vs GraphQL에서 설명합니다.

먼저 설계하기: 리소스와 경로

앱의 명사와 사람들이 그 명사로 하는 일을 적어 보세요. 단순한 예약 앱이라면 다음과 같습니다:

이 경로들은 생성, 조회, 수정, 삭제에 대응합니다. 참고: CRUD란 무엇인가. 따를 만한 규칙은 다음과 같습니다:

• URL에는 동사가 아닌 복수형 명사를 씁니다: /getBookings가 아니라 /bookings.
• 소유 관계를 분명히 할 때만 한 단계까지 중첩합니다: /bookings/{id}/notes.
• CRUD가 아닌 동작은 하위 리소스로 만들 수 있습니다: 애매한 PATCH보다 POST /bookings/{id}/cancel이 더 명확합니다.
• 필드 이름은 일관되게 짓습니다. 예를 들어 어디서나 created_at을 씁니다.

상태 코드와 오류

클라이언트가 텍스트를 해석하지 않고도 무슨 일이 일어났는지 알 수 있도록 표준 HTTP 코드를 사용하세요:

오류는 하나의 일관된 JSON 형태로 반환하세요. 예를 들면 {"error": {"code": "slot_taken", "message": "해당 시간은 더 이상 예약할 수 없습니다."}} 같은 형태입니다. 응답에 스택 트레이스나 데이터베이스 오류를 절대 포함하지 마세요.

선택지와 트레이드오프

단계별 진행

1. 위에서처럼 리소스와 경로를 나열하고, 각 경로를 누가 호출할 수 있는지도 적습니다.
2. 필요한 필드와 관계로 데이터베이스의 데이터를 모델링합니다.
3. 읽기 경로를 먼저 만들고, 그다음 생성, 수정, 삭제를 만듭니다.
4. 모든 쓰기 요청에서 스키마 라이브러리로 입력을 검증합니다: 필수 필드, 타입, 길이, 허용 값. 알 수 없는 필드는 거부합니다.
5. 인증을 추가하고, 그다음 레코드별 권한 부여를 추가합니다. /bookings/42를 불러올 때는 로그인했는지만이 아니라 예약 42가 호출자의 것인지 확인해야 합니다.
6. 모든 목록을 페이지로 나누고 페이지 크기에 상한을 둡니다.
7. 로그인과 비용이 큰 경로에 요청 제한을 겁니다. 요청 제한을 참고하세요.
8. 다른 도메인의 브라우저가 API를 호출해야 할 때만 CORS를 설정하고, 허용할 출처를 명시적으로 나열합니다. CORS 오류 해결 방법에서 마주칠 오류를 설명합니다.
9. 각 경로의 문서와 테스트를 작성합니다. 실패 사례도 포함하세요.
10. 비밀 값은 환경 변수에, HTTPS, 로그, 상태 확인 기능과 함께 배포합니다.

AI 빌더에 줄 프롬프트

스캐폴딩:

예약을 위한 REST API를 만들어 주세요. 경로는 다음과 같습니다: GET /api/health, GET /api/bookings (페이지 나눔, 페이지당 최대 50개), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. 데이터는 우리 데이터베이스에 저장하세요. 요청 본문은 스키마 라이브러리로 검증하고 알 수 없는 필드는 거부하세요. 오류는 {"error": {"code", "message"}} 형태의 JSON으로, 올바른 상태 코드(400, 401, 403, 404, 409)와 함께 반환하세요. 비밀 값은 환경 변수에 보관하세요.

보안:

모든 예약 경로에 로그인을 요구하세요. 모든 읽기, 수정, 삭제에서 서버가 예약이 현재 사용자의 것인지 확인하게 하고, 아니라면 404를 반환하세요. 요청 본문에서 사용자 ID나 역할을 절대 받지 마세요. POST /api/bookings는 사용자당 분당 20회로 요청 횟수를 제한하세요. 오류는 서버에 기록하고 스택 트레이스는 응답에 포함하지 마세요.

문서:

이 경로들의 OpenAPI 설명과, 각 경로의 요청 및 응답 예시가 담긴 짧은 README를 작성하세요.

API 테스트하기

프런트엔드 밖에서 테스트하세요. 공격자가 그렇게 할 것입니다:

• 각 경로가 올바른 입력에 문서화된 형태와 코드로 응답한다
• 누락되었거나 잘못된 필드는 명확한 메시지와 함께 400을 반환한다
• 토큰이 없으면 보호된 모든 경로가 401을 반환한다
• 사용자 A가 ID로 사용자 B의 레코드를 요청하면 404 또는 403을 받는다
• 목록은 페이지로 나뉘고, 지나치게 큰 limit은 상한이 적용된다
• 중복되거나 충돌하는 생성 요청은 500이 아니라 409를 반환한다
• 요청 제한에 걸리면 429가 반환된다
• 오류 응답에 스택 트레이스, SQL, 비밀 값이 없다
• CORS가 의도한 출처만 허용한다

흔한 실수

• 로그인만 확인하고 소유권은 확인하지 않는 것. 가장 흔한 API 구멍입니다. 어떤 로그인 사용자든 ID만 바꾸면 다른 사람의 레코드를 읽을 수 있습니다.
• 클라이언트를 신뢰하는 것. 요청 본문의 가격, 역할, 사용자 ID는 편집될 수 있습니다.
• 데이터베이스 행 전체를 반환하는 것. 비밀번호 해시와 내부 필드가 새어 나갑니다. 각 응답에 무엇을 담을지 직접 고르세요.
• 제한 없는 목록. 모든 레코드를 한 번에 요청하면 앱 전체가 느려질 수 있습니다.
• 본문 안에 오류 메시지가 들어 있는 200 OK. 클라이언트와 모니터링은 실패를 알아차릴 수 없습니다.
• 쿠키를 쓰는 API에서 모든 출처를 허용하는 CORS 설정.
• 상태 확인이나 로그가 없는 것. 장애 소식을 사용자에게 듣고서야 알게 됩니다.

출시 전 전반적인 점검은 AI로 만든 앱을 위한 보안 체크리스트를 참고하세요.

Mythex에서 REST API 만들기

Mythex에 앱의 일부로, 또는 독립된 서비스로 API를 만들어 달라고 요청할 수 있습니다. 문서의 REST API 백엔드 레시피에는 시작 프롬프트가 있습니다. 프레임워크와 경로를 정하고, 명확한 JSON 오류를 요청하고, 비밀 값은 환경 변수에 두고, Dockerfile을 포함하라고 요청하세요. Node, Python, C#, Java 등 컨테이너 백엔드는 Dockerfile로 게시하며, Mythex가 Publish에서 배포를 처리합니다 (API 백엔드). 한 프로젝트에서 웹사이트와 API 서버를 나란히 운영할 수 있고, 미리보기에서 둘 사이를 전환할 수 있습니다. API에 데이터베이스가 필요하면 채팅에서 요청하세요. API 키는 프로젝트 시크릿으로 저장하세요. 그 API 주변의 예약 작업은 백그라운드 작업 실행 방법을 참고하세요.

자주 묻는 질문