앱의 REST API와 API 문서

다른 소프트웨어가 앱 데이터를 써야 할 때가 있습니다. 내 상품을 보여 주는 협력사 웹사이트, 새 주문을 불러오는 스프레드시트, 모바일 앱, Zapier나 n8n 같은 자동화 도구가 그렇습니다. 이런 소프트웨어는 API로 앱과 통신합니다. API는 페이지 대신 데이터로 응답하는 웹 주소(엔드포인트)의 모음입니다. 그중 가장 흔한 방식이 REST API입니다.

MonstarX는 코드 없이 REST API를 만들어 줍니다. 공유할 것을 고르면 몇 초 만에 작동하고, 개발자가 읽을 참조 페이지도 함께 제공됩니다.

어디에서 찾나요?

프로젝트를 열고 상단 바에서 관리자를 클릭한 다음, 관리자 사이드바에서 API를 클릭하세요. 프로젝트 API 화면이 나타납니다. 맨 위에는 API 문서를 게시하는 API 참조 바가 있고, 왼쪽에는 각각 실행 중 또는 초안으로 표시된 엔드포인트가, 그 아래에는 API 키가 있습니다.

엔드포인트는 어떻게 만드나요?

1. 관리자›API에서 새 엔드포인트(또는 엔드포인트 옆의 +)를 클릭하세요.

2. 컬렉션을 고르세요. 엔드포인트가 다룰 테이블로, 예를 들면 Recipes입니다.

3. 작업을 고르세요.

   작업	메서드와 주소	하는 일
   목록	GET /recipes	레코드를 한 페이지씩 반환합니다.
   조회	GET /recipes/{id}	ID로 레코드 하나를 반환합니다.
   생성	POST /recipes	레코드를 추가합니다.
   업데이트	PATCH /recipes/{id}	레코드의 일부 필드를 바꿉니다.
   삭제	DELETE /recipes/{id}	레코드를 삭제합니다.

4. 이름, URL 경로, 원하면 설명도 입력하세요. 이 내용은 API 문서에 표시됩니다.

5. 노출된 필드에서 호출자가 보거나 보낼 수 있는 필드만 정확히 체크하세요. 체크하지 않은 필드는 비공개로 남습니다. 비밀번호나 토큰처럼 민감해 보이는 필드는 항상 제외됩니다.

6. 접근 권한에서 누가 호출할 수 있는지 고르세요(아래 설명 참고).

7. 엔드포인트 게시를 체크하고 엔드포인트 저장 및 게시를 클릭하세요. 게시된 엔드포인트는 실행 중 상태가 되어 바로 요청에 응답합니다. 체크하지 않은 채 엔드포인트 저장을 클릭하면 초안으로 남습니다.

   

목록의 엔드포인트마다 실행 중 또는 초안이 표시됩니다. 엔드포인트 편집 아래에도 같은 상태가 표시되며, 저장하기 전까지 그 뒤에 저장되지 않은 변경 사항이 붙습니다. 엔드포인트를 삭제하지 않고 오프라인으로 돌리려면 엔드포인트 게시의 체크를 해제하고 저장하세요. 삭제를 클릭하면 엔드포인트가 삭제됩니다.

참고

생성, 업데이트, 삭제는 실제 데이터를 바꿉니다. 이런 엔드포인트를 게시하려면 먼저 관리자 탭의 해당 테이블 설정에서 그 작업(추가, 편집, 삭제)을 켜야 합니다. 앱 관리자 패널을 참고하세요.

엔드포인트는 누가 호출할 수 있나요?

접근 권한	호출할 수 있는 대상	쓸 수 있는 작업
공개 읽기	주소를 아는 누구나	목록과 조회만
프로젝트 API 키	프로젝트 API 키 중 하나를 보내는 호출자만	모든 작업

데이터를 바꾸는 엔드포인트에는 항상 키가 필요합니다.

API 키는 어떻게 만드나요?

1. 관리자›API에서 API 키를 클릭하세요.

2. “레시피 위젯 서버”처럼 키를 어디에 쓸지 알 수 있는 이름을 입력하고 키 생성을 클릭하세요.

3. 키를 바로 복사하세요. 키는 mxapi_로 시작하며 다시 표시할 수 없습니다. 비밀번호 관리자나 다른 서비스의 시크릿처럼 안전한 곳에 보관하세요.

키 하나로 프로젝트에서 키로 보호된 모든 엔드포인트에 접근할 수 있으므로, 서비스마다 키를 따로 만드세요. 폐기를 클릭하면 키가 꺼지고, 그 키를 쓰던 곳은 즉시 작동을 멈춥니다.

호출자는 Authorization 헤더에 키를 담아 보냅니다: Authorization: Bearer mxapi_…

주의

API 키는 서버에 두세요. 웹페이지나 모바일 앱에 넣은 키는 누구든 들여다보면 읽을 수 있습니다.

엔드포인트는 어떻게 테스트하나요?

엔드포인트를 열고 테스트를 클릭하세요. 엔드포인트에 필요하면 레코드 ID, Bearer 키, JSON 본문을 입력하고 요청 보내기를 클릭하세요. 상태 코드(200이면 성공), 걸린 시간, 응답이 표시됩니다. 키가 필요한 엔드포인트라면 API 키에서 만든 키 중 하나를 Bearer 키에 붙여 넣으세요.

테스트는 실제로 실행 중인 엔드포인트로 보내지므로 다음을 알아 두세요.

• 초안은 아직 테스트할 수 없습니다. 테스트 탭에 ‘이 엔드포인트는 초안입니다.’라고 표시됩니다. 그곳에서 엔드포인트 저장 및 게시를 클릭해 게시한 뒤 테스트하세요.
• 먼저 변경 사항을 저장하세요. 저장하지 않은 변경 사항이 있으면 테스트 탭에서 테스트 전에 저장하라고 안내하며, 엔드포인트 저장 버튼을 보여 줍니다.

생성, 업데이트, 삭제를 테스트하면 실제 데이터가 바뀝니다.

코드 탭에는 복사해 쓸 수 있는 cURL 명령과, Postman이나 Insomnia 같은 API 도구로 가져올 수 있는 OpenAPI JSON 파일이 있습니다.

API 문서는 어떻게 게시하고 공유하나요?

API 문서는 개발자를 위한 API 참조 페이지입니다. 실행 중인 모든 엔드포인트, 각 엔드포인트의 필드, 키 필요 여부, 직접 실행 입력란, cURL 예시가 들어 있습니다. 엔드포인트를 게시해도 문서는 게시되지 않습니다. 공유할 시점은 직접 정합니다.

1. 엔드포인트를 하나 이상 게시하고 변경 사항을 모두 저장하세요. 그 전까지는 관리자›API 맨 위의 API 참조 바에 게시되지 않음이 표시되고, 무엇이 빠졌는지 알려 줍니다.

2. 문서 게시를 클릭하세요.

   

3. 이제 바에 게시됨이 표시됩니다. 주소를 공유하려면 문서 링크 복사를, 페이지를 보려면 API 키 아래의 API 문서 열기를 클릭하세요. 주소는 https://monstarx.com/api-docs/<your project id> 형태입니다.

monstarx.com

페이지 맨 위에는 프로젝트 이름과 설명, 나열된 엔드포인트 수, 프로젝트 ID, 기본 주소가 표시됩니다. 링크가 있는 누구나 읽을 수 있으며, 검색 엔진에는 색인하지 말라고 알립니다. 실행 중인 엔드포인트만 보여 주고 키는 절대 보여 주지 않습니다. 맨 위의 OpenAPI JSON은 같은 내용을 파일로 제공합니다.

문서를 내리려면 문서 게시 취소를 클릭하세요. 페이지와 OpenAPI 파일은 작동을 멈추지만 엔드포인트는 계속 응답합니다. 모든 엔드포인트를 오프라인으로 돌리면 문서도 함께 게시 취소되며, 준비되면 다시 게시하면 됩니다.

요청과 응답은 어떤 모습인가요?

모든 엔드포인트는 https://monstarx.com/api/rest/<your project id> 아래에 있고, 그 뒤에 경로가 붙습니다.

목록

curl 'https://monstarx.com/api/rest/<project id>/recipes?page=1&limit=25'

{
  "data": [
    { "id": "41a6…", "title": "Street tacos al pastor", "country_code": "MX" }
  ],
  "page": 1,
  "limit": 25,
  "hasMore": false
}

limit는 한 페이지에 담을 레코드 수로 1100이며, 생략하면 25입니다. page는 1100입니다. hasMore는 다음 페이지가 있는지 알려 줍니다.

생성

curl -X POST 'https://monstarx.com/api/rest/<project id>/recipes' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Lemon ricotta pancakes", "country_code": "IT"}'

응답(상태 201)에는 data 아래에 새 레코드와 그 id가 들어 있습니다.

업데이트와 삭제

curl -X PATCH 'https://monstarx.com/api/rest/<project id>/recipes/RECORD_ID' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Fluffy lemon ricotta pancakes"}'

curl -X DELETE 'https://monstarx.com/api/rest/<project id>/recipes/RECORD_ID' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY'

업데이트는 바뀐 레코드로 응답하고, 삭제는 { "deleted": true }로 응답합니다.

보내는 내용의 규칙은 다음과 같습니다.

• Content-Type: application/json을 붙인 JSON 객체여야 하며, 최대 64 KB입니다.
• 노출된 필드만 보낼 수 있고, 각 값은 텍스트(최대 20,000자), 숫자, true/false, null 같은 단순한 값이어야 합니다.
• ID는 설정하거나 바꿀 수 없습니다. 관리자에서 읽기 전용인 필드도 마찬가지입니다.

문제가 있으면 응답에 error 메시지와 상태 코드가 담깁니다. 400(요청이 올바르지 않음), 401(유효한 프로젝트 API 키가 필요함), 403(관리자에서 그 테이블이나 작업을 허용하지 않음), 404(해당 엔드포인트나 레코드가 없음), 409(중복 같은 충돌), 413(응답이 1 MB를 넘음. 노출할 필드를 줄이거나 페이지 크기를 줄이세요)입니다.

자주 묻는 질문

문서 게시를 클릭할 수 없는 이유는 무엇인가요?

문서를 게시하려면 실행 중인 엔드포인트가 하나 이상 있고, 저장하지 않은 변경 사항이 없어야 합니다. 엔드포인트에서 엔드포인트 게시를 체크하고 엔드포인트 저장 및 게시를 클릭한 뒤 문서 게시를 클릭하세요.

API가 작동하려면 앱을 게시해야 하나요?

아니요. API는 프로젝트 데이터베이스를 직접 읽고 쓰므로, 엔드포인트를 게시하는 즉시 작동합니다. 미리보기와 게시된 앱과 같은 데이터를 쓰며, 빌드도 AI도 크레딧도 필요 없습니다.

웹사이트가 브라우저에서 내 API를 호출할 수 있나요?

네, 어떤 웹사이트든 엔드포인트를 호출할 수 있습니다. 웹페이지에서는 공개 읽기 엔드포인트를 쓰고, 키로 보호된 호출은 서버에서 해서 키가 노출되지 않게 하세요.

API 키를 잃어버렸습니다. 다시 볼 수 있나요?

아니요. 키는 한 번만 표시됩니다. 새 키를 만들어 서비스가 새 키를 쓰도록 바꾼 다음, 이전 키를 폐기하세요.

엔드포인트를 게시할 수 없는 이유는 무엇인가요?

생성, 업데이트, 삭제라면 먼저 관리자에서 해당 테이블의 그 작업을 켜세요. 또한 게시된 앱의 데이터베이스가 내 Cloudflare 계정에서 실행되는 앱은 MonstarX에서 엔드포인트를 게시할 수 없습니다. MonstarX에 있는 데이터베이스에는 미리보기용 연습 데이터만 있기 때문입니다.

데이터가 바뀔 때 웹훅을 받을 수 있나요?

관리자 → API에서는 받을 수 없습니다. 이곳은 요청에 응답하는 기능입니다. 대신 MonstarX에 앱에 웹훅을 추가해 달라고 요청하세요. 예를 들어 “주문이 들어오면 이 주소로 POST해 주세요”라고 요청하면 됩니다.

관련 문서

앱 관리자 패널API가 있는 곳. 테이블, 사용자, 활동도 함께 있습니다.

앱 데이터베이스엔드포인트가 읽고 쓰는 테이블.

시크릿과 API 키앱이 다른 서비스에 쓰는 키.

코딩 에이전트에서 MonstarX 쓰기Claude Code, Cursor 등에서 MonstarX를 직접 다루기.