Resource handles

APIEase identifies saved request, widget, variable, and function resources by handle in the public API and CLI workflow.

Use handles when you want resource definitions to live in source control and sync predictably through apiease-cli.

The resource identity model

Each saved resource can have three identity-related values:

• id: server-owned metadata generated by APIEase.
• handle: stable, user-controlled identifier used by public API and CLI workflows.
• name: human-readable display text.

Do not store server-generated id values in repository resource files. Create the file with a handle from the start, then keep using that handle for reads, updates, deletes, request calls, and code review.

Handles must be lowercase slug values using letters, numbers, and single hyphens between words:

product-details-proxy
support-api-key
promo-banner
format-price

Source file fields

Use the identifier field that belongs to the resource's public JSON shape:

Resource	Stable source identifier	Display field	Notes
Request	handle	name	Use the handle as the request identifier in CLI and public API calls.
Widget	handle	name	Use the handle as the widget identifier in CLI, public API, and theme extension settings.
Variable	handle	name	Use handle in System Request arguments whenever possible.
Function	handle	name	The saved resource has a handle; the Liquid function tag still calls Functions by functionName or legacy functionId.

APIEase responses may include both id and handle. Treat id as metadata returned by the server, not as a value to copy into source files.

CLI identifiers

Prefer the handle-named flags for read, update, and delete commands:

Resource	Preferred flag
Request	--request-handle
Widget	--widget-handle
Variable	--variable-handle
Function	--function-handle

Legacy flags such as --request-id, --widget-id, --variable-name, and --function-id remain available as compatibility aliases in current CLI versions. When you use those aliases during migration, pass the handle as the value unless you are intentionally addressing an older server-owned id.

For requests, widgets, variables, and functions, apiease create <resource> --file <path> is idempotent when the file has a valid handle: the CLI creates the resource if it does not exist, or updates the existing resource with that handle if it does. Lookup failures other than not found stop the command instead of falling back to create.

Public API identifiers

The public API item routes use the resource handle as the path value:

/api/v1/resources/requests/{handle}
/api/v1/resources/widgets/{handle}
/api/v1/resources/variables/{handle}
/api/v1/resources/functions/{handle}

For example:

curl -X GET 'https://app-admin.apiease.com/api/v1/resources/requests/product-details-proxy' \
  -H 'x-apiease-api-key: your-apiease-api-key' \
  -H 'x-shop-myshopify-domain: yourstore.myshopify.com'

Some older route parameters, UI internals, and examples may still use names like requestId, widgetId, widgetHandle, widgetName, variableName, or functionId. For public CRUD workflows, treat those as legacy parameter names and pass the resource handle as the value.

Runtime request calls

Several request execution surfaces still use the parameter name requestId, including Liquid call tags, storefront app proxy calls, widget JavaScript, and the remote caller API.

Use the request handle as the requestId value:

{% call { "requestId": "product-details-proxy" } as response %}
{{ response.status }}

const queryParams = new URLSearchParams({
  requestId: 'product-details-proxy',
});

This keeps runtime calls stable without copying APIEase-generated ids into theme code or repository files.

Migrating older source files

For old request source files that still contain id or do not contain handle, run:

apiease create request --file ./resources/requests/product-details-proxy.json --auto-update-source-identifier

That updates only the local request identifier metadata. It does not change request behavior such as type, method, address, parameters, triggers, liquid, or nextRequest.

For older widget source files that still use widgetHandle or widgetName, run:

apiease create widget --file ./resources/widgets/product-details-widget.json --auto-update-source-identifier

That rewrites the local widget JSON before the create-or-update operation. If widgetHandle exists and handle is missing, the CLI writes handle from widgetHandle. If widgetName exists and name is missing, the CLI writes name from widgetName. Existing handle and name values are preserved, unrelated widget fields stay unchanged, and the resulting handle is used for create-or-update behavior.

For variables and functions, update the JSON source manually so it contains handle, the stable source identifier, and no server-owned id.