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

스키마 파일(.sfn)을 만들었다면 이제 설계를 실제 서비스로 바꿀 차례입니다. API빌드를 열면 테이블마다 등록·조회·수정·삭제 API가 준비되고, 각 주소를 누가 사용할 수 있는지도 한 화면에서 확인할 수 있습니다.

필요하면 직접 만든 쿼리 API, 정적 파일 API와 실시간 이벤트도 같은 서비스에 연결할 수 있습니다.

시작하기 전에

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

API 빌드 열기

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

자동 생성 API

테이블마다 기본적으로 아래 5개의 API가 자동 생성됩니다. 필요하면 새로운 API를 직접 추가할 수도 있습니다.

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

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

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

자동 생성되는 5개 API(list/view/create/update/delete)로 부족할 때, 새로운 API 추가하기를 누르면 훨씬 세밀하게 동작을 정의할 수 있습니다.

동작 종류

기본 5개 CRUD 동작 외에, 동작 종류 드롭다운에는 이런 옵션도 있습니다.

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

권한은 REST API와 동일한 3단계

커스텀 엔드포인트의 권한 설정도 자동 생성 API와 같은 방식입니다. 화면에 직접 설명이 나와 있어 헷갈릴 일이 없습니다.

회원 + 추가 조건을 고르면 레벨·소속 팀·관리자 여부·본인(owner) 조건을 조합해서 적용할 수 있습니다. 예를 들어 "레벨 2 이상만", "영업팀 소속만" 같은 조건을 REST API 자동 생성 엔드포인트와 똑같은 방식으로 커스텀 엔드포인트에도 걸 수 있습니다.

SQL을 직접 작성하기

함수 파이프라인 탭에서 커스텀 쿼리 제어를 켜면, 이 엔드포인트가 실행할 기본 SQL 쿼리를 직접 작성하는 편집기가 열립니다.

REST API 목록의 SQL 컬럼에도 이 엔드포인트가 직접 작성한 쿼리를 쓴다는 표시(SQL 배지)가 나타납니다. 자동 생성 API로는 표현할 수 없는 조건 — 예를 들어 "오늘 이 회원이 등록한 행이 3개 이상이면 거부" 같은 집계 기반 조건 — 은 이 SQL 편집기로만 만들 수 있습니다.

함수 파이프라인으로 흐름 제어하기

SQL을 직접 쓰지 않아도, 함수 파이프라인에 미리 준비된 함수를 순서대로 추가해서 요청 처리 흐름을 바꿀 수 있습니다. 함수는 입력 처리·DB 처리·출력 처리 세 단계로 나뉩니다.

권한 설정

API마다 접근 권한을 개별적으로 설정할 수 있습니다. 여기서 말하는 회원은 워크스페이스 회원 계정을 그대로 의미합니다. 별도의 로그인·인증 시스템을 새로 만들 필요 없이, 이미 워크스페이스에 있는 회원·레벨·팀 체계가 API 권한에 그대로 연동되어 있습니다.

배포하기

아래 단계에 따라 배포 정보를 입력합니다.

1. 데이터베이스 이름: 배포 서버에서 사용할 DB의 논리적 이름을 영문으로 입력합니다.
2. 스토리지 엔진: SQLite3, PostgreSQL, MySQL 또는 MariaDB 중 선택합니다. 외부 DB는 host, port, DB 이름, 사용자와 비밀번호를 추가로 입력합니다. MySQL과 MariaDB는 InnoDB 기반 구성을 사용합니다.
3. 보안 및 배포:

모든 항목을 확인한 뒤 배포하기를 누르면 데이터베이스와 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
}

배포와 덮어쓰기

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

알아두기

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

관련 문서

• 스키마 파일(.sfn) 만들기
• 응용편: 실시간 오목 게임 만들기
• 프론트엔드 예시 활용
• 성능과 확장
• 웹스페이스 관리