First use of Caldera REST API

The Caldera Software Suite can be accessed through the Caldera REST API. Companies can use it to link Caldera software with other programs, such as Enterprise Resource Planning (ERP) software or e-commerce solutions.

Start Caldera REST API

Recent versions of our REST API operate as standalone service (a daemon that starts automatically with the system), so they typically do not require manual intervention to start.

The recommended way to manage the Caldera REST API's status, including restarting it to apply changes (e.g., updates to the configuration file, like log level adjustments), is through CalderaDock's Services utility.

Use Caldera REST API

Caldera's Application Programming Interface (API) identifies one or multiple stations over a network as "Services". At the same time, each service can handle "jobs" and "devices".

Here are a few examples of calls to reach our REST API using a simple HTTP tool like cURL.

For API calls and their results, please consult the API Definition or this dedicated help section.

Add a new Service

Starting with v2.0.0, the local Caldera RIP service is no more included by default in new configuration. You need to manually add it with the command (also see the port change to 45344):

  curl --request POST
     --url http://localhost:12340/v1/services 
     --header 'Accept: application/json' 
     --header 'Content-Type: application/json' 
     --data '[
          {
            "host": "XX.XX.XX.XX",
            "type": "calderarip",
            "license": "YYYYYYYYY",
            "port": 45344
          }
        ]'

• Where XX.XX.XX.XX is your host name or IP address
• And YYYYYYYYY is your CalderaRIP access key available in CalderaDock > Licenses

You may be interested in reading: 

• How to add a remote service?
• How to remove a remote service?

Paginate, sort, and filter

Every route returning a list of resources such as services, devices, jobs, etc, is paginated. This means you can retrieve at most 100 resources in a row by default, then use the links to the next and previous pages in the response’s link header to retrieve the next and previous pages. Make sure to use these links instead of generating your own URLs.

Some additional information about pagination is given in the response’s headers:

• caldera-page: The current page offset returned in the response (1-based offset).
• caldera-limit: The maximum number of resources on a page (defaults to 100).
• caldera-total-results: The total number of resources matching the query.
• link: Links to the next and previous pages (if any).

You can change this limit of 100 elements by setting the limit parameter in the URL, eg. GET /v1/jobs?limit=50 to get at most 50 jobs.

In addition to pagination, the Caldera REST API also provides sorting and filtering facilities through URL parameters:

• sort: Used to sort the resources against a given sort expression, using the following syntax: sort=<field1>:(asc|desc)[,<field2>:(asc|desc)...]
• filter: Used to filter the resources against a given filter expression, using the following syntax:

  • Basic filtering: <path-to-field1>=<value1>[&<path-to-field2>=<value2>...]
    For example, GET /v1/devices?name=CalderaDriver001&state=running will return a device named CalderaDriver001 and state is running.

      Info

    Note that the filter is applied case-insensitively to values, meaning that in the given example, a running device whose name is CalderaDriver001 will also be returned.

    Rather than a simple property name, you can specify a path to a property using . as a delimiter, eg. GET /v1/jobs?idents.service=********.

  • Advanced filtering: Same as basic filtering with the possibility to use * as a wildcard for a value, and | to specify a union of possible values.
    For example, GET /v1/devices?name=*Caldera*&state=running|stopped will return the list of devices whose name contain the term Caldera and state is eitherrunning or stopped.

    You can combine these two operators in the same value, eg. GET /v1/jobs?name=*ShowRoom*|*Reception*

As for pagination, some information about sorting and filtering is returned in the response’s headers:

• caldera-sort: The sort expression got from the request.
• caldera-filter: The filter expression got from the request.

Get Services list

For a description of what a service is, please consult the Glossary.

curl http://127.0.0.1:12340/v1/services

This command will output a list of registered services and their status in a JSON format.

Get Devices list

For a description of what a service is, please consult the Glossary.

curl http://127.0.0.1:12340/v1/devices

This command will output a list of all devices accessible via the registered services and their status in a JSON format.

Get Jobs list

For a description of what a service is, please consult the Glossary.

curl http://127.0.0.1:12340/v1/jobs

This command will output a list of all jobs accessible via the registered services in a JSON format.

Configure the Caldera REST API

In rare cases, such as debugging or unexpected behavior, you can modify the REST API's configuration JSON file. Please refer to the dedicated article for more information.