mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-04-22 13:06:16 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

2.5.2 docs (#247)

Browse source 
* docs: Changes for v2.5.2 release

* docs: Remove -X POST

Curl automatically uses POST for -d and --data-binary.

I intentionally left it in to be explicit to learners, but
maybe best practices are better.

* api: /adapt endpoint and Etag usage

* api: Minor tweaks

* Alright fine

* Clarify Etag usage

* CEL embedded matchers

* Oops

* Lots more adjustments

Co-authored-by: Francis Lavoie <lavofr@gmail.com>
This commit is contained in:
Matt Holt 2022-07-12 12:52:18 -06:00 • committed by GitHub
parent 522d1961d1
commit 7819a84e59
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
30 changed files with 529 additions and 164 deletions
Download patch file Download diff file Expand all files Collapse all files

23
src/docs/markdown/api-tutorial.md
View file

@ -68,7 +68,6 @@ Save this to a JSON file:
Then upload it:
<pre><code class="cmd bash">curl localhost:2019/load \
-X POST \
-H "Content-Type: application/json" \
-d @caddy.json
</code></pre>
@ -104,7 +103,6 @@ Let's change our welcome message from "Hello world!" to something a little more
Save the config file, then update Caddy's active configuration by running the same POST request again:
<pre><code class="cmd bash">curl localhost:2019/load \
-X POST \
-H "Content-Type: application/json" \
-d @caddy.json
</code></pre>
@ -130,15 +128,18 @@ Using the request URI's path, we can traverse into the config structure and upda
<pre><code class="cmd bash">curl \
localhost:2019/config/apps/http/servers/example/routes/0/handle/0/body \
-X POST \
-H "Content-Type: application/json" \
-d '"Work smarter, not harder."'
</code></pre>
<aside class="tip">
Every time you change the config using the API, Caddy persists a copy of the new config so you can <a href="/docs/command-line#caddy-run"><b>--resume</b> it later</a>!
Every time you change the config using the API, Caddy persists a copy of the new config so you can [**--resume** it later](/docs/command-line#caddy-run)!
</aside>
You can verify that it worked with a similar GET request, for example:
<pre><code class="cmd bash">curl localhost:2019/config/apps/http/servers/example/routes</code></pre>
@ -149,10 +150,14 @@ You should see:
[{"handle":[{"body":"Work smarter, not harder.","handler":"static_response"}]}]
```
<aside class="tip">
You can use the <a href="https://stedolan.github.io/jq/">jq command</a> to prettify JSON output: <b><code>curl ... | jq</code></b>
You can use the [`jq` command](https://stedolan.github.io/jq/) to prettify JSON output: **`curl ... | jq`**
</aside>
<aside class="complete">Traverse config</aside>
**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:
@ -171,7 +176,6 @@ We can give our handler object an [`@id` tag](/docs/api#using-id-in-json) to mak
<pre><code class="cmd bash">curl \
localhost:2019/config/apps/http/servers/example/routes/0/handle/0/@id \
-X POST \
-H "Content-Type: application/json" \
-d '"msg"'
</code></pre>
@ -186,10 +190,14 @@ This adds a property to our handler object: `"@id": "msg"`, so it now looks like
}
```
<aside class="tip">
<b>@id</b> tags can go in any object and can have any primitive value (usually a string). <a href="/docs/api#using-id-in-json">Learn more</a>
**@id** tags can go in any object and can have any primitive value (usually a string). [Learn more](/docs/api#using-id-in-json)
</aside>
We can then access it directly:
<pre><code class="cmd bash">curl localhost:2019/id/msg</code></pre>
@ -198,7 +206,6 @@ And now we can change the message with a shorter path:
<pre><code class="cmd bash">curl \
localhost:2019/id/msg/body \
-X POST \
-H "Content-Type: application/json" \
-d '"Some shortcuts are good."'
</code></pre>