사람함께에이전트▾

사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.

함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.

에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.

일반▾

인증과 권한 에이전트를 위한 OAuth 스키마 설계 텍스트 검색 엣지 컴퓨팅 파일 관리 Single Sign-On DataList & Enum

인터페이스▾

CRUD Endpoint MCP 서버 에이전트 채팅 Form

관측성▾

로깅 의존성 주입 에러 처리 메트릭

성능▾

캐싱 이미지 최적화 지연 로딩 쿼리 변경 큐 실시간

네이티브▾

설정 Push Notifications Deep Links UI & Keyboard 데스크톱 배포

개발▾

문서화 스키마 문서 스크립트 콘솔 도커 쿠버네티스 PWA 테스트

API 문서

Akan은 앱의 fetch로 API 탐색기를 그립니다. signal의 모든 엔드포인트와 인자, 가드, 반환 타입이 나옵니다. 같은 화면에서 엔드포인트를 바로 호출할 수 있으니 단순한 목록이 아닙니다.

이 페이지에서 쓰는 말

용어설명

signal

모듈의 엔드포인트를 선언하는 파일입니다. signal 하나가 API 문서 한 장이 됩니다.

fetch

@apps/<app>/client에서 가져오는 앱의 API 클라이언트입니다. 탐색기는 여기서 엔드포인트를 읽습니다.

guard

누가 엔드포인트를 호출할 수 있는지 정하는 클래스입니다. Public, User, Admin 같은 것이 있습니다.

JWT

로그인 토큰입니다. 붙여넣으면 가드가 걸린 엔드포인트를 그 계정으로 호출할 수 있습니다.

pubsubmessage

WebSocket 엔드포인트의 두 종류입니다. 서버가 밀어 주는 구독과, 답이 리스너로 돌아오는 메시지입니다.

문서 한 장에 담기는 것

요약

전체 엔드포인트, REST, WebSocket, MCP 툴로 공개된 엔드포인트의 개수입니다.

Endpoints · REST API · Web Socket · MCP Tools

도구 모음

Base URL을 보여 주고, 가드 필터와 JWT, 엔드포인트 검색을 설정합니다.

Signal.Doc.Setting

REST API

모든 query와 mutation을, 자동 생성된 CRUD와 slice 조회까지 포함해 보여 줍니다. 행마다 Reference와 Try it이 있습니다.

GET · POST

Web Socket

pubsub 행은 구독해서 도착하는 프레임을 바로 보여 줍니다. message 행은 Listen으로 답을 기다리고 Send로 보냅니다.

Subscribe · Listen · Send

Zone으로 문서 띄우기

탐색기는 관리자나 개발자만 보는 페이지에 둡니다. 첫 대상으로는 base signal이 좋습니다. 모든 앱에 들어 있고 ping 엔드포인트가 단순합니다.

apps/myapp/page/(admin)/api/_index.tsx

refNamestring필수

문서로 만들 signal입니다. base나 product 같은 모듈 이름을 넣습니다.

fetchFetchProxy선택

기본값은 앱 자신의 fetch입니다. 마운트되지 않은 signal은 등록되지 않았다고 나옵니다.

openAllboolean선택

모든 엔드포인트 행을 펼칩니다. 엔드포인트가 많은 signal에서는 빼 두세요.

route는 서버 페이지로 남습니다. Signal.Doc의 멤버마다 클라이언트 경계가 따로 있어 래퍼가 필요 없고, JavaScript로 가는 것은 탐색기뿐입니다.
devOnly: true는 프로덕션에서 이 route를 뺍니다. akan start에서는 열리고 akan build 결과에는 들어가지 않습니다. 프로덕션의 관리자 도구로 쓸 거라면 이 옵션을 지우고 route를 관리자만 볼 수 있게 막으세요.

다른 부품

보통은 Signal.Doc.Zone이면 충분합니다. 일부만 필요할 때는 더 작은 부품을 씁니다:

컴포넌트설명

Signal.Doc.Zone

signal 하나의 문서 전체입니다. 요약, 도구 모음, REST와 WebSocket 목록이 들어 있습니다.

Signal.Doc.Explorer

마운트된 signal 전체를 사이드바에 두고 처음 열 때 마운트합니다. include, exclude, libs, groupBy로 범위를 정합니다.

Signal.Doc.Setting

도구 모음만 따로 그립니다. search와 onSearch를 넘기면 검색창이 붙습니다.

Signal.Doc.DocSignals

앱이 마운트한 모든 signal을 접이식 행 하나씩으로 보여 주며, REST 엔드포인트만 나옵니다.

Signal.RestApi.Endpoints

signal 하나의 REST 엔드포인트, 또는 endpoints에 적은 것만 보여 줍니다. 아래 ping 실습이 이것입니다.

엔드포인트 직접 호출하기

아래는 base 문서의 실제 ping 행이며, 이 문서 사이트의 서버를 호출합니다. "ping"이라는 문자열을 돌려줍니다.

행에서 Try it을 누릅니다.
Send Request를 누릅니다.
응답 칸에 "ping"이 나오는지 확인합니다.

GET/pingPublicMCP refused

Ping

Ping 테스트 엔드포인트

it declares `mcp: false`, so it is deliberately off the agent shelf. HTTP still serves it.

반환

String!

예시

"String"

ping에 MCP refused가 뜨는 것은 정상입니다. 가드를 선언하지 않았고, MCP는 누가 호출할 수 있는지 가드로 밝힌 엔드포인트만 공개합니다.

행 읽는 법

구성 요소설명

GETPOST

메서드 배지입니다. query는 GET, mutation은 POST로 표시됩니다.

가드 배지

엔드포인트가 선언한 가드입니다. 가드가 없으면 배지도 없습니다.

MCP 배지

에이전트가 MCP 툴로 호출할 수 있는지 알려 줍니다. 거부된 행은 그 아래에 이유가 나옵니다.

Reference

인자(path, query, body, form data), 반환 타입, 응답 예시를 보여 줍니다.

Try it

예시 값이 채워진 입력칸, 복사할 수 있는 요청 경로, Send Request 버튼이 있습니다.

base signal의 다른 엔드포인트

base에는 종류별로 단순한 엔드포인트가 하나씩 있습니다. 문서 전체를 띄우면 모두 눌러 볼 수 있습니다:

엔드포인트 · 종류
↳ 해 볼 것
ping query · GET
인자가 없습니다. `"ping"`을 돌려줍니다.
pingParam query · GET
path 파라미터 `id`를 받아 `pingParam: <id>`를 돌려줍니다.
pingQuery query · GET
쿼리 문자열 `id`를 받아 `pingQuery: <id>`를 돌려줍니다.
pingBody mutation · POST
body 필드 `data`를 받아 `pingBody: <data>`를 돌려줍니다.
wsPing message
Listen을 누른 뒤 Send를 누르면 `wsPing: <data>` 답이 스트림에 나타납니다.
pubsubPing pubsub
Subscribe와 Unsubscribe를 눌러 볼 수 있는 room입니다.

인증과 가드

User나 Admin 같은 가드가 걸린 엔드포인트는 로그인한 호출자가 필요합니다. JWT를 한 번 붙여넣으면 Try it에서 보내는 모든 REST 요청에 그 토큰이 실립니다.

도구 모음의 Auth 칸에서 Anonymous를 누릅니다.
Bearer token에 토큰을 붙여넣습니다. 아래 Account decoded에 토큰 속 계정 정보가 나오니, 어떤 role로 테스트하는지 확인하세요.
Set Authorization을 누르면 버튼이 Authorized로 바뀝니다.

도구 모음

항목설명

Base URL

탐색기가 호출하는 서버입니다. 누르면 복사됩니다.

Guards

signal이 선언한 가드 중 고른 것으로 행을 거릅니다. 가드가 없는 엔드포인트는 Public으로 칩니다.

Auth

Anonymous 또는 Authorized로 표시되며, 누르면 JWT 입력 창이 열립니다.

Search endpoints

엔드포인트 이름이나 경로로 행을 거릅니다.

서명은 서버가 확인합니다. 이 창은 토큰의 payload를 읽기만 하고, 서명 검증은 요청을 보낼 때 서버가 합니다.
설정은 화면 전체에 하나입니다. 가드 필터와 JWT는 store에 있으므로, 화면의 모든 엔드포인트 목록과 Try it 요청이 같은 값을 따릅니다.
REST에만 쓰입니다. WebSocket 실습은 붙여넣은 토큰이 아니라 페이지 자신의 소켓 연결로 동작합니다.

JWT는 개발자 테스트용으로만 씁니다. 실제 사용자의 토큰이 아니라 테스트 계정의 토큰을 붙여넣으세요.

꿀팁

API 문서는 개발자나 관리자에게만 보여 주세요. route에 devOnly: true를 다는 것이 가장 간단합니다.
작게 시작하세요. 큰 도메인을 문서화하기 전에 base나 작은 모듈로 먼저 익히세요.
수동 점검용이지 테스트가 아닙니다. 빠르게 확인할 때 쓰고, 자동 테스트를 대신하지는 않습니다.

이어서 읽기

Signal 컴포넌트→

Signal 부품과 멤버 전체 목록입니다.

MCP 서버→

엔드포인트가 에이전트에게 공개되거나 거부되는 이유를 다룹니다.

인증과 권한→

엔드포인트에 달 수 있는 가드를 다룹니다.

테스트→

signal을 자동으로 검증하는 테스트를 다룹니다.

이전데스크톱 배포 다음스키마 문서