API 튜토리얼

원문 보기 위키 갱신 2026.10.03

API 튜토리얼 (API Tutorial)

이 튜토리얼은 프로그래밍 방식으로 자동화할 수 있는 Caddy의 admin API를 사용하는 방법을 보여줘요.

출처: Caddy 공식 문서

본문

이 튜토리얼은 프로그래밍 방식으로 자동화할 수 있는 Caddy의 admin API를 사용하는 방법을 보여줘요.

목표(Objectives):

🔲 데몬 실행 (Run the daemon)
🔲 Caddy에 config 주기 (Give Caddy a config)
🔲 config 테스트 (Test config)
🔲 활성 config 교체 (Replace active config)
🔲 config 탐색 (Traverse config)
🔲 @id 태그 사용 (Use @id tags)

사전 요구 사항(Prerequisites):

기본 터미널 / 명령줄 기술
기본 JSON 경험
PATH 안의 caddy와 curl

Caddy 데몬을 시작하려면 run 하위 명령을 사용해요:

caddy run

데몬 실행 (Run the daemon)

이 명령은 영원히 차단하는데, 무엇을 하고 있을까요? 지금으로선... 아무것도요. 기본적으로 Caddy의 설정("config")은 비어 있어요. 다른 터미널에서 admin API로 이를 확인할 수 있어요:

curl localhost:2019/config/

config를 줘서 Caddy를 유용하게 만들 수 있어요. 한 방법은 /load 엔드포인트에 POST 요청을 하는 거예요. 다른 HTTP 요청처럼 할 방법이 많지만, 이 튜토리얼에서는 curl을 사용할 거예요.

첫 번째 config

요청을 준비하려면 config를 만들어야 해요. Caddy의 설정은 단순히 JSON 문서(또는 JSON으로 변환되는 무엇이든)예요.

config 파일은 필수가 아니에요. 설정 API는 파일 없이도 항상 사용할 수 있어서, 자동화할 때 편리해요. 이 튜토리얼은 손으로 편집하기 편리하므로 파일을 사용해요.

이것을 JSON 파일로 저장해요:

{
	"apps": {
		"http": {
			"servers": {
				"example": {
					"listen": [":2015"],
					"routes": [
						{
							"handle": [{
								"handler": "static_response",
								"body": "Hello, world!"
							}]
						}
					]
				}
			}
		}
	}
}

그런 다음 업로드해요:

curl localhost:2019/load \
	-H "Content-Type: application/json" \
	-d @caddy.json

파일 이름 앞에 @를 빼먹지 마세요. 이게 curl에 파일을 보내고 있다는 걸 알려줘요.

Caddy에 config 주기 (Give Caddy a config)

새 GET 요청으로 Caddy가 새 config를 적용했는지 확인할 수 있어요:

curl localhost:2019/config/

localhost:2015를 브라우저에서 열거나 curl을 사용해 동작하는지 테스트해요:

curl localhost:2015
Hello, world!

config 테스트 (Test config)

*Hello, world!*가 보이면 축하해요 — 동작하고 있어요! config가 기대한 대로 동작하는지 확인하는 건, 특히 프로덕션에 배포하기 전에는 항상 좋은 습관이에요.

인사말을 "Hello world!"에서 좀 더 동기부여가 되는 "I can do hard things."로 바꿔볼게요. config 파일에서 이렇게 변경해, handler 객체가 이제 이렇게 보이게 해요:

{
	"handler": "static_response",
	"body": "I can do hard things."
}

config 파일을 저장한 다음, 같은 POST 요청을 다시 실행해 Caddy의 활성 설정을 업데이트해요:

curl localhost:2019/load \
	-H "Content-Type: application/json" \
	-d @caddy.json

활성 config 교체 (Replace active config)

확인 차원에서 config가 업데이트됐는지 검증해요:

curl localhost:2019/config/

브라우저에서 페이지를 새로고침(또는 curl 재실행)해 테스트하면, 영감을 주는 메시지가 보일 거예요!

Config 트래버설 (Config traversal)

작은 변경에 전체 config 파일을 업로드하는 대신, Caddy API의 강력한 기능을 사용해 config 파일을 전혀 건드리지 않고 변경을 할 수 있어요.

위에서처럼 전체 config를 교체해 프로덕션 서버에 작은 변경을 하는 건 위험할 수 있어요. 파일 시스템에 루트 접근 권한이 있는 것과 같거든요. Caddy의 API는 변경 범위를 제한해서 config의 다른 부분이 실수로 바뀌지 않도록 보장할 수 있게 해줘요.

요청 URI의 경로를 사용해 config 구조를 탐색하고 메시지 문자열만 업데이트할 수 있어요(잘리면 오른쪽으로 스크롤):

curl \
	localhost:2019/config/apps/http/servers/example/routes/0/handle/0/body \
	-H "Content-Type: application/json" \
	-d '"Work smarter, not harder."'

API로 config를 변경할 때마다 Caddy는 새 config의 사본을 유지해서 나중에 --resume할 수 있어요!

비슷한 GET 요청으로 동작했는지 확인할 수 있어요. 예:

curl localhost:2019/config/apps/http/servers/example/routes

이렇게 보여야 해요:

[{"handle":[{"body":"Work smarter, not harder.","handler":"static_response"}]}]

jq 명령을 사용해 JSON 출력을 예쁘게 만들 수 있어요. curl ... | jq

Config 트래버스 (Traverse config)

중요 참고: 명백하지만, 한 번 API로 원래 config 파일에 없는 변경을 하면 config 파일은 낡게 돼요. 처리할 방법이 몇 가지 있어요:

caddy run의 --resume을 사용해 마지막 활성 config를 사용해요.
config 파일 사용과 API를 통한 변경을 섞지 말고, 하나의 진실 소스(source of truth)를 가져요.
후속 GET 요청으로 Caddy의 새 설정을 내보내요(처음 두 옵션보다 덜 권장).

JSON에서 `@id` 사용하기

Config 트래버설은 확실히 유용하지만, 경로가 조금 길지 않나요?

handler 객체에 @id 태그를 줘서 접근하기 더 쉽게 만들 수 있어요:

curl \
	localhost:2019/config/apps/http/servers/example/routes/0/handle/0/@id \
	-H "Content-Type: application/json" \
	-d '"msg"'

이것은 handler 객체에 "@id": "msg" 속성을 추가해, 이제 이렇게 보여요:

{
	"@id": "msg",
	"body": "Work smarter, not harder.",
	"handler": "static_response"
}

@id 태그는 어떤 객체에도 들어갈 수 있고 어떤 원시 값(보통 문자열)도 가질 수 있어요. 더 알아보기

그런 다음 직접 접근할 수 있어요:

curl localhost:2019/id/msg

이제 더 짧은 경로로 메시지를 바꿀 수 있어요:

curl \
	localhost:2019/id/msg/body \
	-H "Content-Type: application/json" \
	-d '"Some shortcuts are good."'

그리고 다시 확인해요:

curl localhost:2019/id/msg/body

@id 태그 사용 (Use @id tags)

더 알아보기 (Learn more)

Caddy 공식 문서

API 튜토리얼