API 생성기

API 생성기는 관리자가 저장 프로시저와 연결된 API 엔드포인트를 생성, 수정, 보호, 관리할 수 있는 기능입니다. Route URL, HTTP Method, 요청 JSON 구조, 파라미터 매핑, 보안 정책, Webhook 설정, 실행 가이드를 한 화면에서 관리할 수 있습니다.

웹사이트 프론트엔드, 외부 시스템, 자동화 스크립트, 연동 서비스에서 사용할 API를 안전하게 만들고 관리할 때 사용하는 기능입니다.

화면 개요

API 생성기는 크게 API Management, Security Policies, API Edit, Webhook / Execution Guide 영역으로 구성됩니다.

API Management

API Management 화면에서는 등록된 API 목록을 확인할 수 있습니다. API 이름 또는 코드로 검색할 수 있으며, 상태와 보안 방식으로 필터링할 수 있습니다.

주요 버튼

검색 및 필터

• Search: API 이름 또는 API 코드로 검색합니다.
• Status: 활성 또는 비활성 상태로 필터링합니다.
• Security: 보안 방식 또는 정책 기준으로 필터링합니다.
• Page Size: 한 페이지에 표시할 API 개수를 선택합니다.

API 목록

API 목록에는 ID, API 이름, Route, Method, 저장 프로시저, 보안 방식, 상태 등이 표시됩니다. 등록된 API가 없는 경우 No APIs have been registered. 메시지가 표시됩니다.

Security Policies

Security Policies는 API 요청을 인증하는 방법을 정의합니다. 보안 정책은 기본 정책으로 사용할 수도 있고, 개별 API에서 선택해서 사용할 수도 있습니다.

정책 생성

API Key와 Token 값은 외부에 노출되면 안 됩니다. 안전하게 보관하고 필요할 경우 주기적으로 변경하세요.

API Edit

API Edit 화면은 하나의 API 엔드포인트를 설정하는 화면입니다. 기본 정보, 요청/응답 설정, 저장 프로시저 파라미터, 실행 설정, Webhook 설정을 관리할 수 있습니다.

Basic Information

SP List

SP List 버튼을 클릭하면 저장 프로시저 목록 팝업이 열립니다. 저장 프로시저를 선택하면 요청 JSON 구조와 파라미터 구조를 생성할 수 있습니다.

Request / Response Settings

이 영역에서는 API가 받을 요청 데이터와 저장 프로시저 파라미터 매핑 정보를 설정합니다.

Request JSON Schema

API 요청 시 전달해야 하는 JSON 구조를 정의합니다.

{
    "Keyword": "",
    "IsActive": true
}

Parameter Map JSON

요청 JSON 값을 저장 프로시저 파라미터에 매핑합니다.

{
    "@Keyword": "{{Keyword}}",
    "@IsActive": "{{IsActive}}"
}

Generate from SP

선택한 저장 프로시저의 파라미터를 기준으로 Request JSON Schema와 Parameter Map JSON을 자동 생성합니다.

SP Parameter Structure

선택한 저장 프로시저의 파라미터 구조를 표시합니다. 파라미터명, 데이터 타입, 길이, 모드, 순서 등을 확인할 수 있습니다.

Operation Settings

Operation Settings는 API가 요청을 받을 때 어떻게 동작할지 설정하는 영역입니다.

Webhook

Webhook은 API 실행 후 결과를 외부 URL로 전송하는 기능입니다. Webhook 전송이 실패해도 원래 API 응답 자체가 실패 처리되지는 않습니다.

Webhook Headers 예시

{
    "Authorization": "Bearer your-token",
    "X-SOURCE": "ApiGenerator"
}

Webhook Payload 예시

{
    "apiName": "{{ApiName}}",
    "routeUrl": "{{RouteUrl}}",
    "success": {{Success}},
    "message": "{{Message}}",
    "traceId": "{{TraceId}}",
    "requestJson": {{RequestJson}},
    "responseJson": {{ResponseJson}}
}

사용 가능한 Webhook Placeholder

• {{ApiName}}
• {{RouteUrl}}
• {{Success}}
• {{Message}}
• {{TraceId}}
• {{RequestJson}}
• {{ResponseJson}}

API Execution Guide

API Execution Guide는 저장된 API 설정을 기준으로 자동 생성되는 사용 가이드입니다. 호출 URL, 보안 Header, 요청 Body, 실행 규칙, 다양한 언어별 호출 예제를 제공합니다.

생성되는 예제 종류

• Overview / Call Rules
• curl
• JavaScript fetch
• Axios / jQuery
• C# / HttpClient
• ASP.NET MVC
• Python / requests
• Postman / Bruno

권장 작업 순서

1. Admin > Site > API Generator 메뉴로 이동합니다.
2. Security Policies를 클릭하여 기본 API 보안 정책을 생성합니다.
3. API Management 화면으로 돌아옵니다.
4. Create New를 클릭합니다.
5. API 이름과 Route URL을 입력합니다.
6. HTTP Method를 선택합니다.
7. SP List를 사용해 저장 프로시저를 선택합니다.
8. Generate from SP로 요청 JSON과 파라미터 매핑을 생성합니다.
9. Operation Settings를 설정합니다.
10. 필요한 경우 Webhook을 설정합니다.
11. API를 저장합니다.
12. Execution Guide를 열어 생성된 예제로 API를 테스트합니다.

자주 사용하는 작업

주의사항

• API 생성 및 수정 권한은 신뢰할 수 있는 관리자에게만 부여해야 합니다.
• 의도적으로 공개하는 API가 아니라면 반드시 보안 정책을 적용하세요.
• 민감한 저장 프로시저를 Public API로 노출하지 마세요.
• 저장 전 Request JSON과 Parameter Map JSON을 반드시 확인하세요.
• Timeout Seconds를 설정하여 장시간 실행되는 요청을 제한하세요.
• Webhook은 수신 URL이 신뢰할 수 있고 안정적인 경우에만 사용하세요.
• API Key 또는 Token은 주기적으로 변경하는 것이 좋습니다.

문제 해결

관리 권장 사항

• API 이름과 Route URL은 명확하게 작성하세요.
• API 전용으로 설계된 저장 프로시저를 사용하는 것이 좋습니다.
• Body JSON을 받는 API는 POST 방식을 사용하는 것이 좋습니다.
• GET은 Query String 접근이 안전한 경우에만 허용하세요.
• Public 사용자에게 노출되는 JavaScript 안에 Secret 값을 넣지 마세요.
• Webhook Payload는 작고 명확한 구조로 유지하세요.
• API를 공유하기 전 Execution Guide로 반드시 테스트하세요.

API 생성기는 백엔드 데이터베이스 기능을 외부에서 호출 가능한 Endpoint로 노출할 수 있습니다. API를 활성화하기 전에 보안 정책, 저장 프로시저 로직, 파라미터 매핑을 반드시 검토하세요.