API 빌드 및 데이터베이스 배포하기

API빌드에서는 스키마 파일(.sfn)의 테이블마다 만들어지는 등록·조회·수정·삭제 API와 접근 권한을 확인하고, 데이터베이스와 함께 배포합니다. 직접 만든 쿼리 API, 정적 파일 API와 실시간 이벤트도 같은 화면에서 추가할 수 있습니다.

시작하기 전에

• 필요 권한: 데이터베이스 사용 권한이 부여된 사용자
• 사전 준비: 스키마 파일(.sfn)을 먼저 만들어야 합니다.

API 빌드 열기

스키마 화면 상단의 API빌드 탭을 선택하면 테이블별로 자동 생성된 API 목록을 확인할 수 있습니다.

자동 생성 API

테이블마다 다음 5개 API가 자동으로 만들어집니다.

새로운 API 추가하기 (Custom Endpoint)에서는 쿼리와 응답 형태를 직접 정한 API를 추가할 수 있습니다. 정적 파일 API 추가로는 워크스페이스의 JSON, XML, HTML, 이미지와 바이너리 파일을 파일 형식에 맞게 제공할 수 있습니다.

정적 파일 또는 폴더를 API로 제공하기

1. 정적 파일 API 추가를 선택합니다.
2. 저장 공간에서 팀 스페이스 또는 개인 스페이스를 선택합니다.
3. 공개 대상에서 파일 하나 또는 폴더 목록 · 파일 읽기를 선택한 뒤 파일 선택 또는 폴더 선택으로 원본을 지정합니다.
4. 폴더를 선택했다면 허용 확장자와 하위 폴더 포함을 설정합니다. 확장자를 비워 두면 모든 형식이 대상이 됩니다.
5. 응답 방식에서 브라우저에 내용을 표시할지(브라우저에서 바로 표시), 파일로 받을지(다운로드) 선택합니다.
6. 엔드포인트 권한을 확인한 뒤 스키마를 배포합니다.

단일 파일은 설정한 엔드포인트에서 내용을 응답합니다. 폴더는 파일 목록 JSON과 목록 항목의 id로 내용을 읽는 주소를 함께 만듭니다. id는 경로를 기준으로 만들어지므로 파일 이름을 바꾸거나 옮기면 함께 바뀝니다. 클라이언트에서는 목록에서 받은 최신 id 또는 viewUrl을 사용합니다.

기능 엔드포인트에서는 실시간 소켓, 파일·이미지 업로드와 AI 응답처럼 서비스 전체에서 사용하는 기능의 권한을 설정합니다.

실시간 이벤트와 REST 묶음 가져오기

실시간 소켓의 이벤트 정의에서는 이벤트만 작성하거나, 이벤트에 필요한 표와 REST 설정이 포함된 JSON 또는 YAML 묶음을 가져올 수 있습니다.

1. AI 답 붙여넣기를 선택하고 묶음을 붙여넣습니다. 직접 준비한 묶음도 같은 형식으로 붙여넣을 수 있습니다.
2. 기존 이벤트를 유지하려면 이름 기준 병합, 현재 이벤트 전체를 바꾸려면 전체 교체를 선택합니다.
3. 적용 미리보기에서 추가·변경·삭제될 이벤트와 추가될 표·컬럼·REST 수를 확인합니다.
4. 기존 REST와 충돌하거나 형식이 자동으로 정리·제외된 항목을 확인합니다. 기존 REST를 바꿔야 할 때만 겹치는 REST 설정을 덮어쓰기를 선택합니다.
5. 서버 검사 결과를 확인하고 오류를 수정한 뒤 적용을 선택합니다.

가져오기는 편집 중인 스키마만 바꾸며, 실제 서비스에는 배포하기를 완료해야 반영됩니다. 배포할 때 서버가 이벤트와 REST 규칙을 다시 검사하며, 통과하지 못하면 배포되지 않습니다.

커스텀 엔드포인트로 CRUD 밖의 API 만들기

자동 생성되는 5개 API(list/view/create/update/delete)로 부족하면 새로운 API 추가하기 (Custom Endpoint)를 선택해 동작을 직접 정의합니다.

동작 종류

동작 종류에서는 기본 CRUD 동작 외에 다음 항목을 선택할 수 있습니다.

대상 범위는 컬렉션(테이블 전체나 여러 레코드, 보통 :id 없는 경로), 단일 항목(특정 레코드 하나), 명령(CRUD에 맞지 않는 명령형 엔드포인트) 중에서 선택합니다.

커스텀 엔드포인트 권한

커스텀 엔드포인트도 자동 생성 API와 같은 방식으로 회원만, 회원 + 추가 조건, 누구나 중 하나를 선택합니다.

회원 + 추가 조건을 선택하면 레벨, 소속 팀, 관리자 여부, 본인(owner) 조건을 조합할 수 있습니다. 예를 들어 "레벨 2 이상만", "영업팀 소속만" 같은 조건을 걸 수 있습니다.

SQL을 직접 작성하기

처리 흐름 탭의 기본 쿼리에는 이 엔드포인트가 실행할 SQL을 직접 작성하는 편집기가 있습니다. 자동 생성 API에서는 기본 쿼리를 직접 작성한 SQL로 바꾸면 같은 편집기가 열립니다.

직접 작성한 SQL을 쓰는 엔드포인트는 REST API 목록의 처리 열에 SQL 배지가 표시됩니다. "오늘 이 회원이 등록한 행이 3개 이상이면 거부"처럼 집계가 필요한 조건은 이 SQL 편집기로만 만들 수 있습니다.

SQL 검사와 매개변수 확인하기

SQL을 입력하면 브라우저에서 문법과 현재 스키마의 표·컬럼을 검사합니다. 오류와 확인 필요 항목에 행·열이 표시되면 해당 안내를 선택해 편집기의 문제 위치로 이동합니다. 배포 영역에서도 오류가 있는 SQL을 열 수 있습니다.

이 검사는 실제 DB에서 쿼리를 실행하지 않습니다. 사용하는 DB 엔진의 함수, 접근 권한과 실제 데이터에 따른 결과는 배포 후 API를 호출해 확인합니다.

매개변수에는 SQL에서 사용하는 :name 형식의 매개변수가 표시됩니다. :id, :user_id, :nick, :now는 서버가 채우는 예약 값입니다. 그 밖의 값은 조회 요청에서는 쿼리스트링, 쓰기 요청에서는 입력 처리를 거친 본문에서 가져오며, 값이 없으면 NULL로 처리합니다.

처리 흐름으로 요청 처리 바꾸기

처리 흐름 탭에서 준비된 함수를 순서대로 추가하면 SQL 없이도 요청 처리 방식을 바꿀 수 있습니다. 함수는 입력 처리, DB 처리, 출력 처리로 나뉩니다.

권한 설정

API마다 접근 권한을 따로 설정합니다. 여기서 회원은 워크스페이스 회원 계정이며, 워크스페이스의 회원·레벨·팀 체계가 API 권한에 그대로 적용됩니다.

배포하기

배포 영역은 API빌드 화면 맨 아래에 고정되어 있어 API 목록을 스크롤해도 항상 보입니다.

1. 배포 영역에서 배포하기를 선택해 배포 설정을 펼칩니다. 이 단계에서는 아직 배포되지 않습니다.
2. 기본 설정의 데이터베이스 식별자에 배포 서버에서 사용할 DB의 논리적 이름을 영문으로 입력합니다.
3. 샘플 화면이 필요하면 기본 설정의 클라이언트 배포 경로에서 샘플 프론트엔드(index.html, test.html, README.md 등)를 만들 경로를 선택합니다.
4. 스토리지의 스토리지 엔진 모드에서 SQLite3, PostgreSQL, MySQL 또는 MariaDB를 선택합니다. 외부 DB는 호스트, 포트, DB 이름, 사용자와 비밀번호를 추가로 입력합니다. MySQL과 MariaDB는 InnoDB 기반으로 구성됩니다.
5. API 접근을 특정 IP로 제한하려면 고급 설정의 IP 제한에 허용할 IP를 입력합니다.
6. 설정을 확인한 뒤 배포하기를 다시 선택합니다.

배포가 끝나면 데이터베이스와 API가 준비됩니다. 클라이언트 배포 경로를 지정했다면 API를 시험할 수 있는 샘플 화면도 함께 만들어집니다. 화면을 바꾸는 방법은 프론트엔드 샘플 확인하기를 참고하세요.

API 호출 예시

배포된 API는 다음 형식으로 호출합니다. 예시의 테이블 이름은 user_profile입니다.

GET  /api/web/{dbName}/user_profile/list
GET  /api/web/{dbName}/user_profile/view/{id}
POST /api/web/{dbName}/user_profile/create
PUT  /api/web/{dbName}/user_profile/update/{id}
DELETE /api/web/{dbName}/user_profile/delete/{id}

등록(POST) 요청 예시:

POST /api/web/{dbName}/user_profile/create
Content-Type: application/json

{
  "email": "user@example.com",
  "is_active": true
}

오류 응답 읽기

요청이 실패하면 HTTP 상태와 code 또는 errorCode를 확인합니다. 오류 코드는 언어와 관계없이 같으므로 로그인 요청·재시도 같은 동작은 코드로 판단하고, message는 화면 표시에만 사용합니다.

웹스페이스의 기본 오류 안내는 한국어, 영어, 일본어, 중국어(간체), 독일어를 지원합니다. 로그인한 회원의 언어 설정을 먼저 사용하고, 설정이 없거나 지원하지 않는 언어이면 요청의 Accept-Language를 참고합니다. 둘 다 맞지 않으면 영어로 안내합니다. 외부 API 연동에서는 표시 문구를 비교하지 않습니다.

예를 들어 로그인이 필요한 요청은 다음 정보를 반환합니다.

{
  "code": "WEBSPACE_LOGIN_REQUIRED",
  "errorCode": "WEBSPACE_LOGIN_REQUIRED",
  "message": "로그인이 필요합니다."
}

위 필드가 오류 응답에서 확인할 핵심 정보입니다. 전체 응답 형식은 REST API, 정적 파일, 관리 API마다 다를 수 있습니다.

• 입력값 검증 응답은 기존 형식인 ok: false와 errors 목록을 사용합니다. HTTP 200이어도 ok를 확인하고, 각 항목의 field·code·message로 문제를 안내합니다.
• WebSocket 오류는 type: "error" 메시지의 data 안에서 확인합니다. 기존 분류용 key는 유지되며 code·errorCode가 오류 원인을 구분합니다.
• 서버의 실제 파일 경로, SQL과 내부 오류 원문은 사용자에게 반환하지 않습니다. 운영자가 서버 로그를 확인해야 하는 오류라면 발생 시각, 요청 경로, HTTP 상태와 오류 코드를 함께 전달합니다.

배포와 덮어쓰기

기존 데이터가 있는 스키마의 덮어쓰기는 서버의 배포 정책을 따릅니다. 조직 정책에 따라 금지하거나 관리자 또는 지정된 배포 담당자만 실행하도록 제한할 수 있습니다. 구조를 바꾸기 전에는 영향을 받는 컬럼과 API, 백업과 복구 절차를 확인합니다.

알아두기

• API는 SetFN 로그인 세션으로 인증하며, 인증되지 않은 요청은 거부됩니다. 권한을 누구나로 설정한 API는 예외입니다.
• 스키마 구조를 바꾸면 API 엔드포인트도 함께 갱신되므로 기존 연동 코드의 호환성을 확인합니다.
• SQLite3 데이터는 해당 서버의 웹스페이스 저장소에, 외부 엔진 데이터는 관리자가 설정한 DB에 저장됩니다.
• 목록의 필터·정렬·페이지 크기는 서버가 허용한 쿼리 범위 안에서 사용합니다.
• 외부 사이트에서 호출한다면 관리자의 허용 Origin과 CSP 설정을 함께 확인합니다.

관련 문서

• 스키마 파일(.sfn) 만들기
• 실시간 오목 게임 만들기
• 프론트엔드 샘플 확인하기
• 성능과 확장
• 웹스페이스 관리 시작하기