Automatically insert details on how to perform an action with the API and CLI.
{{< automation-instructions
command="<doctl command>"
path="<api endpoint>" verb="<http verb>"
>}}
This shortcode uses the DigitalOcean OpenAPI spec (stored in the /data
folder) and YAML metadata of the doctl
CLI reference to generate detailed instructions on performing actions via the API and CLI.
You cannot currently use this shortcode with the Spaces or Metadata APIs.
To include doctl
instructions, define the following parameters. Omit them to exclude doctl
instructions.
command
: The full doctl
command that performs the action
.To include API instructions, define the following parameters. Omit them to exclude API instructions.
path
: The API endpoint that performs the action
. You can find this in the right column of the API reference docs.
For example, the blue badge that says POST next to the Create a New Droplet API action uses the /v2/droplets
endpoint.
verb
: The HTTP verb (get
, post
, delete
, put
, or patch
) that corresponds with the action.
Optionally, include the action
parameter to override the default description synopsis from the API spec or CLI docs:
action
(optional): A short, English description of the action being taken.{{< automation-instructions action="create a Droplet"
command="doctl compute droplet create"
path="/v2/droplets" verb="post"
>}}
Renders to:
{{< automation-instructions action="create a Droplet" path="/v2/droplets" verb="post" >}}
Renders to:
{{< automation-instructions command="doctl compute droplet create" >}}
Renders to:
When an API or CLI call requires the resources to be in a certain state, call it out in the adjacent text.
For an example, see the Droplet resizing docs, which call out that the Droplet must be powered down before resizing.
When an API or CLI call requires a slug as an input value, call it out in the adjacent text.
For an example, see the Droplet creation docs, which call out how to retrieve valid region, machine, and image slugs.
Sometimes the CLI and API approaches are very different; it’s okay to include one or the other, or to split up the instructions and provide details in the adjacent text.
For an example, see the Droplet rebuilding docs, which call out that when using the API to rebuild a Droplet, there is no specific command, like there is for doctl
, and you have to set the action type to rebuild
within the general droplet-action
call.
Also see the Droplet metrics docs, for which there are only API instructions, as doctl
does not currently have a way to monitor things like CPU and memory usage.