매니저 HTTP API

매니저 HTTP API

편집기, Ember, ash, CLI가 모두 같은 API를 씁니다. 계약은 docs/api/manager.openapi.yaml이고, 매니저가 정확히 그 경로만 내는지 테스트가 확인합니다.

두 모드

바깥에서의 접근은 항상 전용 매니저를 거칩니다. 커널은 루프백에만 열립니다.

인증

모든 요청은 Authorization: Bearer <token>을 붙입니다. 이벤트 스트림과 공유 링크만 ?token=도 받습니다. 브라우저의 EventSource는 헤더를 붙일 수 없기 때문입니다. GET /health는 토큰이 필요 없습니다.

공유 토큰은 커널 하나에 묶입니다. 다른 커널을 가리키면 403이 아니라 404로 답해서, 어떤 커널이 있는지 드러내지 않습니다.

경로

출력은 nbformat 4 출력 스키마를 그대로 씁니다. 그래서 Jupyter 출력을 읽는 도구는 이것도 읽습니다. 떠 있는 매니저는 /docs/에서 API 문서 페이지도 냅니다.

예시

# 파일의 커널을 띄우거나 붙습니다. 떠 있었으면 200, 새로 띄웠으면 201.
curl -s -X POST "$URL/api/kernels" -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' -d '{"path": "/home/me/experiments/train.py"}'

# 1번과 3번 셀을 실행. 바쁘면 409 대신 대기열에 넣음.
curl -s -X POST "$URL/api/kernels/$KID/runs" -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"mode": "cells", "cells": [1, 3], "params": {"lr": 0.02}, "on_busy": "queue"}'

# 이벤트 따라가기. EventSource는 헤더를 못 붙이므로 SSE는 ?token=도 받음.
curl -N "$URL/api/kernels/$KID/events?token=$TOKEN"

# 멈춤은 인터럽트입니다.
curl -s -X POST "$URL/api/kernels/$KID/interrupt" -H "Authorization: Bearer $TOKEN"

커널이 바쁠 때 들어온 두 번째 실행은 요청에 "on_busy": "queue"가 없으면 현재 실행 정보와 함께 409를 받습니다.

이벤트

GET /api/kernels/{kernel_id}/events는 Server-Sent Events 스트림입니다. 실행 시작과 끝, 셀 시작과 끝, 출력, 문서 변경이 옵니다. SSE id는 커널의 이벤트 번호입니다. 다시 붙을 때 Last-Event-ID를 주면, 커널의 재전송 버퍼에 남아 있는 동안은 놓친 이벤트를 받습니다.

버전 없음

경로에는 버전이 없습니다(INTENT D16). API는 더하기만 합니다. 필드, 선택 요청 필드, 경로, 오류 코드를 더할 뿐 이름을 바꾸거나 지우지 않습니다. 대체된 필드는 deprecated 표시와 함께 남습니다. 클라이언트는 모르는 필드를 무시합니다.

바뀌는 것