Skip to main content

Contract format

How an apic contract file is laid out, what each field means, and how templates and the project config work. For the commands that read and write these files, see COMMAND.md.

A contract is a single JSON object describing one endpoint. See apic-core/src/templates/contract.json for the built-in template apic create seeds from (and Templates for how to make it your own), or example/ for complete projects.

{
"name": "update-user",
"description": "Update a user",
"method": "PUT",
"url": "https://api.example.com/users/{id}",
"query": [
{
"name": "notify",
"value": "true",
"description": "Send a notification email",
"required": false
}
],
"headers": [
{ "name": "Content-Type", "value": "application/json", "required": true },
{ "name": "Authorization", "value": "Bearer {token}", "required": true }
],
"request": {
"name": "Rizki Rakasiwi"
},
"responses": [
{
"code": 200,
"description": "User updated",
"headers": [
{ "name": "X-Request-Id", "value": "abc-123", "required": false }
],
"schema": {
"status": 200,
"message": "OK"
}
}
]
}

A body is a raw JSON payload, the exact thing you would send or receive. The request body is written directly under request; a response body is written under the response's schema key. There is no separate field-level schema: the payload is the contract's source of truth for a body's shape, and apic read prints it verbatim. Omit request (or a response's schema) when there is no body.

Fields​

FieldRequiredDescription
nameyesEndpoint name.
descriptionnoShort description of the endpoint.
methodyesHTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS.
urlyesRequest URL as a single free-form string, e.g. https://api.example.com/users/{id}. Path parameters are written inline as {name} tokens.
querynoArray of query parameters; see below.
headersyesArray of request headers; see below.
requestnoRequest body: the raw JSON payload, written directly. Omit it when the endpoint has no body.
multipartnoA multipart request body, as an array of parts; see Multipart bodies. Use it instead of request, not alongside it.
responsesyesArray of responses; see below.

Each query parameter:

FieldRequiredDescription
nameyesParameter key, e.g. page.
valuenoExample value, e.g. 2.
descriptionnoWhat the parameter is for.
requirednoWhether the parameter is required (default false).

Each header (request or response):

FieldRequiredDescription
nameyesHeader name, e.g. Authorization.
valueyesExample value, e.g. Bearer {token}.
requirednoWhether the header is required (default false).

Each response:

FieldRequiredDescription
codeyesHTTP status code, e.g. 200.
descriptionyesShort description, e.g. OK.
headersnoArray of response headers (same shape as request headers).
schemanoThe response body: the raw JSON payload for this response.
multipartnoA multipart response body, as an array of parts. Use it instead of schema, not alongside it.

Path parameters are not a separate section: write them inline in the url string as {name} (e.g. {id} in .../users/{id}).

The request body has no wrapper key, it is the JSON value itself. A response's body lives under schema (not example). Contracts written for the older { "example": ... } body shape do not carry over and must be updated.

Multipart bodies​

A request or a response can carry a multipart body (form data and file uploads) instead of a JSON one. Each part is one form field:

"multipart": [
{ "name": "title", "value": "Hello", "required": true },
{
"name": "avatar",
"filename": "avatar.png",
"contentType": "image/png",
"description": "Profile picture",
"required": false
}
]
FieldRequiredDescription
nameyesForm field name.
valuenoExample value for a text part.
filenamenoPresent on a file part, e.g. avatar.png. A part with a filename is a file part; one without is a text part.
contentTypenoThe part's own media type, e.g. image/png.
descriptionnoWhat the part is for.
requirednoWhether the part is required (default false).

A request sets request or multipart, and a response sets schema or multipart, never both: an HTTP message carries one body, and apic validate rejects a contract that sets both. In the desktop GUI, the body-type dropdown switches a body between JSON and Multipart while editing.

Templates​

A template is a starter contract that apic create -f <file> copies from when you scaffold a new endpoint. apic init seeds one at .apic/template/convention.json from the built-in default; a project can hold several named templates (apic create --template <name> authors more), and --use-template <name> chooses which one seeds a new contract (with several and no --use-template, apic create uses convention.json). A template is never overwritten once it exists.

The project template is overlaid onto the built-in default, so it only needs to carry the fields you want to standardize, it can be a small partial contract. It lives in .apic/template/, committed to the repo like everything else, so the whole team scaffolds from the same starting point.

Put your general API design in the template​

The template is the single thing every new contract inherits from, so it is where a team's shared API conventions belong. Encode the general design once and every endpoint starts consistent, with none of the boilerplate re-typed:

  • Base URL and versioning, e.g. https://api.example.com/v1/... (or a {{baseUrl}}/{{base_path}}/... placeholder), so every endpoint targets the same host and version.
  • Standing headers, the ones every request carries, Content-Type, Authorization: Bearer {token}, a DeviceID/AppID, each with its required flag set the way your API expects.
  • A house response envelope, if your API always wraps responses (e.g. { "statusCode", "message", "error", "value" }), put that shape in the template's example responses so new endpoints follow it by default.
  • Common query parameters, pagination (page, limit) or filter keys that most list endpoints share.

Because scaffolding always starts from these defaults, the template turns your API design guidelines into something executable: consistency becomes the path of least resistance, drift shows up as a diff in review, and adding an endpoint is "edit what's different" instead of "remember every convention". When the convention itself changes, you edit one file and every new contract picks it up.

Variables and environments​

Strings in the URL, query, headers and body can hold variables. $name, ${name} and {{name}} are all replaced by the variable's value, and $$ stands for a literal $. A name with no value is left as written, and apic send warns about it on stderr. Path params written {name} are filled from the same values.

Values come from an environment and from --var flags, and the flags win. An environment is a TOML file of name = "value" pairs. .apic/env/<name>.toml is shared with the team. .apic/env/<name>.local.toml holds your own values and overrides the shared file. Local files are gitignored through .apic/.gitignore.

In a multipart body, a file part sends the file at its value, resolved relative to the project root. SENDING.md has the full guide.

Configuration​

apic init writes .apic/config.toml:

name = "apic"
version = "0.1.0"

[root]
working_dir = "api-contract"

working_dir is stored relative to the project root, so .apic/config.toml is safe to commit and share, it resolves correctly on any clone. apic locates the project by walking up from the current directory to find the .apic directory, so commands work from anywhere inside the project tree.