Sending requests
apic send fires the request a contract describes and prints the real response. Values that change between servers or people, such as the base URL or an access token, live in environments and fill the contract's variables at send time.
The desktop GUI can send too, see the Sending section of GUI.md.
Your first request
mkdir -p .apic/env
cat > .apic/env/dev.toml <<'EOF'
baseUrl = "https://api.dev.example.com"
EOF
cat > .apic/env/dev.local.toml <<'EOF'
access_token = "paste-your-token-here"
EOF
apic send -f auth/login --env dev
With a contract whose URL is $baseUrl/auth/login and a header Authorization: Bearer $access_token, this sends POST https://api.dev.example.com/auth/login with your token, prints the response body on stdout, and prints a line such as HTTP 200 OK · 143 ms on stderr.
To try it without a server of your own, this repository has a demo environment and contracts in example/demo/ that call the public mock APIs dummyjson.com and httpbin.org. From the repository root, run apic send -f demo/login --env demo, then put the returned accessToken in .apic/env/demo.local.toml as access_token = "..." to make demo/me work. demo/get_product needs --var id=1, and demo/echo_upload sends a multipart file.
Variables
Any string in a contract's URL, query, headers or body can hold variables.
| You write | It becomes |
|---|---|
$name | the value of name |
${name} | the value of name, for when text follows directly, as in ${version}beta |
{{name}} | the value of name, the form Postman uses |
{name} in the URL | the value of name, for path params such as /users/{id} |
$$ | a literal $ |
A name starts with a letter or _ and continues with letters, digits and _. Only names that have a value are replaced. Everything else stays exactly as written, so $set, $5 or a lone $ in a JSON example is never touched. When the URL or a header uses a name with no value, apic send prints a warning and sends the text as written.
In a JSON body, variables are filled inside string values. Keys, numbers and booleans are sent as they are.
Environments
An environment is a name, such as dev or staging, backed by up to two TOML files in .apic/env/:
| File | Purpose | In git |
|---|---|---|
<name>.toml | values the team shares, such as base URLs and client IDs | committed |
<name>.local.toml | your own values, such as tokens and passwords | ignored |
Both files are flat lists of name = "value" lines, and every value is a string. When the same name is in both files, the local one wins. An environment exists as soon as either file exists, so a local-only environment is fine.
apic keeps the line env/*.local.toml in .apic/.gitignore. apic init writes it, and every apic send adds it again if it went missing, so a local file stays out of commits. Check with git status before your first commit anyway if your repository has unusual ignore rules.
# .apic/env/staging.toml
baseUrl = "https://api.staging.example.com"
app_id = "apic-staging"
# .apic/env/staging.local.toml
access_token = "eyJhbGciOi..."
apic env lists the environments and marks those with a local file. It never prints values.
$ apic env
dev (+local)
staging
Without --env, no environment is used.
One-off values
--var NAME=VALUE sets a variable for one send and wins over the environment. It is repeatable. It is the usual way to fill a path param:
apic send -f users/get --env dev --var id=42
apic send -f users/get --env dev --var id=42 --var access_token="$TOKEN"
When the URL still has a {name} with no value, apic send stops before sending and tells you which --var to pass.
What gets sent
| Part | Sent as |
|---|---|
| method | the contract's method |
| URL | url with variables filled, then every query entry appended as name=value, URL-encoded |
| headers | every headers entry, values filled |
| JSON body | request, filled and compact, with Content-Type: application/json unless the contract sets its own Content-Type |
| multipart body | multipart, as multipart/form-data with its own boundary |
In a multipart body, a text part sends its value. A file part, one with a filename, sends the contents of the file whose path is in value, relative to the project root:
{ "name": "avatar", "value": "fixtures/avatar.png", "filename": "avatar.png", "contentType": "image/png" }
A file part with no path, a missing file, or a path that leads outside the project stops the send.
The URL must start with http:// or https:// once variables are filled. A URL still starting with $baseUrl means the variable has no value.
Dry run
--dry-run prints the request send would build and sends nothing. Every variable that has a value is shown as $name instead of the value, in the URL, path params, query, headers, body and multipart parts, so the output never contains a secret from your environment files. The Target: line shows the real scheme, host and port the request would go to, without any user:pass@.
apic send -f auth/login --env dev --dry-run
Target: https://api.example.com
POST $baseUrl/auth/login
Authorization: Bearer $token
Content-Type: application/json
{
"email": "$email",
"password": "$password"
}
A multipart body is listed one part per line. File parts show their path, filename, content type and size, never their contents:
part avatar: file fixtures/avatar.png as avatar.png, image/png, 20480 bytes
part note: hello $name
A dry run refuses wherever send would, for example on an unfilled path param, and warns about each undefined variable. With --json it prints {"dry_run": true, "method", "target", "url", "headers", "body", "undefined"}, plus a parts array for a multipart body. --dry-run cannot be combined with -i.
Output and exit codes
The response body goes to stdout. On a terminal, a JSON body is pretty-printed and coloured, and NO_COLOR turns the colour off. When piped, the body is written exactly as received, so apic send -f login --env dev | jq .data works. The status summary and the warnings go to stderr.
-i prints the status line and the response headers on stdout before the body.
| Exit code | Meaning |
|---|---|
| 0 | the server replied, with any status, 4xx and 5xx included |
| 1 | the send was refused, for example an unfilled path param |
| 2 | no contract matches the query, or several do |
| 3 | the contract is not valid |
| 4 | the connection failed or timed out |
Up to 5 redirects are followed. A redirect drops the Authorization header. The timeout is 30 seconds, changed with --timeout <secs>.
Moving from {{name}} to $name
{{name}} keeps working. To switch a project to the $name form, run:
apic vars --convert # lists each file and how many it would change
apic vars --convert --write # rewrites them
It covers every contract and the project templates. A variable followed directly by a name character becomes ${name}, so {{id}}x turns into ${id}x.