Руководство по API

Это руководство покажет вам, как использовать администрируемый API Caddy, что позволяет автоматизировать работу программно.

Цели:

• 🔲 Запустить демон
• 🔲 Предоставить Caddy конфигурацию
• 🔲 Проверить конфигурацию
• 🔲 Заменить активную конфигурацию
• 🔲 Переходить по конфигурации
• 🔲 Использовать @id теги

Предварительные требования:

• Базовые навыки работы с терминалом/командной строкой
• Базовые знания JSON
• caddy и curl в вашей переменной среды PATH

Для запуска демона Caddy используйте подкоманду run:

caddy run

Это блокирует выполнение бесконечно, но что он делает? В данный момент... ничего. По умолчанию конфигурация Caddy ("config") пуста. Мы можем проверить это, используя администрируемый API Caddy в другом терминале:

curl localhost:2019/config/

Мы можем сделать Caddy полезным, предоставив ему конфигурацию. Один из способов сделать это — отправить POST-запрос на конечную точку /load. Как и любой HTTP-запрос, существует множество способов сделать это, но в этом руководстве мы будем использовать curl.

Ваша первая конфигурация

Для подготовки запроса нам нужна конфигурация. Конфигурация Caddy — это просто JSON-документ (или любой объект, преобразуемый в JSON).

Сохраните это в 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

Мы можем убедиться, что Caddy применил нашу новую конфигурацию, отправив другой GET-запрос:

curl localhost:2019/config/

Проверьте, что это работает, перейдя по ссылке localhost:2015 в вашем браузере или используя curl:

curl localhost:2015
Hello, world!

Если вы видите Привет, мир!, поздравляем — это работает! Всегда полезно убедиться, что ваша конфигурация работает так, как вы ожидаете, особенно перед развертыванием в производство.

Давайте изменим приветствие с «Привет, мир!» на что-то более мотивирующее: «Я могу делать сложные вещи». Внесите это изменение в ваш файл конфигурации, чтобы объект обработчика теперь выглядел так:

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

Сохраните файл конфигурации, а затем обновите активную конфигурацию Caddy, повторно отправив тот же POST-запрос:

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

Для проверки убедитесь, что конфигурация была обновлена:

curl localhost:2019/config/

Проверьте это, обновив страницу в браузере (или повторно выполнив curl), и вы увидите вдохновляющее сообщение!

Переход по конфигурации

Вместо загрузки всего файла конфигурации для небольшого изменения давайте воспользуемся мощной функцией API Caddy, чтобы внести изменения без изменения файла конфигурации.

Используя путь URI запроса, мы можем перейти в структуру конфигурации и обновить только строку сообщения (убедитесь, что прокрутили вправо, если текст обрезался):

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

Вы можете проверить, что это сработало, с помощью аналогичного GET-запроса, например:

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

Вы должны увидеть:

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

Важное примечание: Это должно быть очевидно, но как только вы используете API для внесения изменений, которые не находятся в вашем исходном файле конфигурации, ваш файл конфигурации становится устаревшим. Есть несколько способов справиться с этим:

• Используйте параметр --resume команды caddy run, чтобы использовать последнюю активную конфигурацию.
• Не смешивайте использование файлов конфигурации с изменениями через API; используйте один источник истины.
• Экспортируйте новую конфигурацию Caddy с последующим GET-запросом (менее рекомендуется, чем первые два варианта).

Использование @id в JSON

Переход по конфигурации, безусловно, полезен, но пути слишком длинные, не так ли?

Мы можем добавить объекту обработчика тег @id, чтобы упростить доступ:

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

Это добавляет свойство к нашему объекту обработчика: "@id": "msg", поэтому он теперь выглядит так:

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

Тогда мы можем получить доступ к нему напрямую:

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