Consuming the RESTful API from a Custom Application

The REST API provided by the REST plug-in allows you to send requests to the vision system and to query information from the vision system. This is done via HTTP endpoints that are composed of a predefined (base) URL and an HTTP method. You can build an application customized to your use case and send requests to the available endpoints to query information from the vision system and to control it by triggering actions.

The REST API provides two different types of HTTP methods: GET and POST. GET methods are used to query information from the vision system, for example, to get a list of available recipes or to get the results of an execution. POST methods are used to trigger a specific action such as preparing a recipe or to start an execution.

The section below shows which endpoints are provided by the REST API and for what purpose each of the endpoints can be used. In summary, they can be used for the following purposes:

• Getting the system status and sending actions to the vision system.
• Preparing and unpreparing recipes.
• Starting running jobs, that is, a single or continuous execution.
• Getting information about the recipes, running jobs, events, and errors.
• Getting the results including image results.

Available Endpoints

The following table gives an overview of the available endpoints of the REST API and thus an overview of the API storage semantics of the resources.

URI	HTTP method	Description
/errors	GET	Returns a list of errors.
/errors/{error_id}	GET	Returns error information for a specific error ID.
/events	GET	Returns a list of events.
/events/{event_id}	GET	Returns information about a specific event.
/jobs	GET	Returns a list of all known jobs.
/jobs/{job_id}	GET	Returns information about an explicit job for a specific recipe.
/jobs/{job_id}/results	GET	Returns a list of results associated to a job.
/recipes	GET	Returns a list of available recipes.
/recipes/actions	POST	Sends an action for a specific recipe.
/recipes/actions/{action_id}/status	GET	Returns the status of the given action for a specific recipe.
/recipes/{recipe_id}/jobs	GET	Returns a list of all jobs started for a specific recipe.
/recipes/{recipe_id}/results	GET	Returns a list of results of a specific recipe.
/results	GET	Returns a list of results.
/results/{result_id}	GET	Returns the result information for a specific result ID.
/results/{result_id}/data/{data_index}.jpg	GET	Returns JPEG image data of a specific data component within the result for a specific result ID.
/results/{result_id}/data/{data_index}.png	GET	Returns PNG image data of a specific data component within the result for a specific result ID.
/state_machine	GET	Returns the current status of the system.
/state_machine/actions	POST	Sends an action to the vision system.
/state_machine/actions/{action_id}/status	GET	Returns the status of the specified action.

For more information on the REST API and the available endpoints, see the documentation of the REST API which can be accessed in the built-in web application via the "API Docs" menu entry.

Configuring the Number of Available Results

Querying results will only succeed if the respective result data is still available. Otherwise, an error will be returned. Whether the result data is still available depends on the size of the respective result stores. When using the REST plug-in, different result stores are used for the results.

The REST plug-in comes with an in-memory database with a specific capacity for results. All results of an execution, except image data, will be stored in the result store of the plug-in. The size of this result store is defined in the configuration of the plug-in. For more information, see the section In-Memory Database in Configuring the Plug-in. If the number of results exceeds the defined buffer size, the oldest results will be removed.

In contrast, image results are stored separately in the in-memory database provided by the vision system and they are connected to their respective result in the result store. The buffer size of this result store is also configurable. However, if the number of results exceeds the defined buffer size, the oldest images will be removed. If you want to preserve the images longer, you can use the extended image storage. It can be used to keep the images that will be removed from the in-memory storage of the vision system. This way, the image results are still available. However, as soon as the size of the extended image storage is exceeded, it will also remove the oldest images from this storage.

You can adjust the size of the in-memory storage and the settings for the extended image storage in the MERLIC preferences within the MERLIC Creator or in the INI file via the respective ini options. For more information, see MERLIC Preferences and The MERLIC INI File.