API Tutorial

This tutorial will show you how to use Caddy's admin API, which makes it possible to automate in a programmable fashion.

Objectives:

• 🔲 Run the daemon
• 🔲 Give Caddy a config
• 🔲 Test config
• 🔲 Replace active config
• 🔲 Traverse config
• 🔲 Use @id tags

Prerequisites:

• Basic terminal / command line skills
• Basic JSON experience
• caddy and curl in your PATH

To start the Caddy daemon, use the run subcommand:

This blocks forever, but what is it doing? At the moment... nothing. By default, Caddy's configuration ("config") is blank. We can verify this using the admin API in another terminal:

We can make Caddy useful by giving it a config. One way to do this is by making a POST request to the /load endpoint. Just like any HTTP request, there are many ways to do this, but in this tutorial we'll use curl.

Your first config

To prepare our request, we need to make a config. Caddy's configuration is simply a JSON document (or anything that converts to JSON).

Save this to a JSON file:

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

Then upload it:

We can verify that Caddy applied our new config with another GET request:

Test that it works by going to localhost:2015 in your browser or using curl:

If you see Hello, world!, then congrats -- it's working! It's always a good idea to make sure your config works as you expect, especially before deploying into production.

Let's change our welcome message from "Hello world!" to something a little more motivational: "I can do hard things." Make this change in your config file, so that the handler object now looks like this:

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

Save the config file, then update Caddy's active configuration by running the same POST request again:

For good measure, verify that the config was updated:

Test it by refreshing the page in your browser (or running curl again), and you will see an inspirational message!

Config traversal

Instead of uploading the entire config file for a small change, let's use a powerful feature of Caddy's API to make the change without ever touching our config file.

Using the request URI's path, we can traverse into the config structure and update only the message string (be sure to scroll right if clipped):

Every time you change the config using the API, Caddy persists a copy of the new config so you can --resume it later!

You can verify that it worked with a similar GET request, for example:

You should see:

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

You can use the jq command to prettify JSON output: curl ... | jq

Important note: This should be obvious, but once you use the API to make a change that is not in your original config file, your config file becomes obsolete. There are a few ways to handle this:

• Use the --resume of the caddy run command to use the last active config.
• Don't mix the use of config files with changes via the API; have one source of truth.
• Export Caddy's new configuration with a subsequent GET request (less recommended than the first two options).

Using @id in JSON

Config traversal is certainly useful, but the paths are little long, don't you think?

We can give our handler object an @id tag to make it easier to access:

This adds a property to our handler object: "@id": "msg", so it now looks like this:

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

@id tags can go in any object and can have any primitive value (usually a string). Learn more

We can then access it directly:

And now we can change the message with a shorter path:

And check it again: