Skip to content

Resource Search API Documentation

Wogeez Engine Wogeez Engine

This documentation presents two API endpoints dedicated to resource search, which can include devices, scenarios, etc. These endpoints enable quick and real-time retrieval of the necessary data for effective search and filtering.

Search Workflow

To use these endpoints effectively, you must first call an API to retrieve the definition of the filters. Once the filters are obtained, you can call another API to apply those filters and retrieve the search results, which can be sorted and/or paginated as needed.

sequenceDiagram
  autonumber
  User->>AuthService: Request JWT Token (username, password)
  AuthService-->>User: Return JWT Token

  User->>Search Filters API: Call GET /resources/search/filters (Authorization: Bearer JWT Token)
  Search Filters API-->>User: Return list of filters

  User->>Search API: Call GET /resources/search (Authorization: Bearer JWT Token, filters)
  Search API-->>User: Return search results

Retrieving Search Filters

This endpoint allows you to retrieve a list of filters applicable for refining a resource search. It can be used to dynamically display available filtering options in a user interface. For example, if an application supports searching for devices, this endpoint can return the types of available resources.

Retrieving Search Filters
curl -X GET "https://api-v2.wogeez.com/resources/search/filters" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Accept: application/json"
Response
{
  "items": [
    {
      "field": "company",
      "definition": {
        "type": "ENUMERATION",
        "parameters": [
          {
            "name": "Corentin Organization",
            "value": "d013e5cb-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "count": 1
          }
        ]
      },
      "scope": null
    },
    {
      "field": "health.versionCode",
      "definition": {
        "type": "ENUMERATION",
        "parameters": [
          {
            "name": "3.0.0",
            "value": "3.0.0",
            "count": 1
          }
        ]
      },
      "scope": "DEVICE"
    },
    {
      "field": "connection.state",
      "definition": {
        "type": "ENUMERATION",
        "parameters": [
          {
            "name": "CONNECTED",
            "value": "CONNECTED",
            "count": 1
          }
        ]
      },
      "scope": "DEVICE"
    }
  ]
}

The JSON structure follows a hierarchical model:

Field Description Example
field Represents the name of the resource field that is being described or filtered. company.id
scope Indicates the type of resource the field applies to, such as a device or another. DEVICE
definition Provides detailed information about the field, including its type and possible values.
definition.type Specifies the type of filter applied to the field (e.g., enumeration of possible values). ENUMERATION
definition.parameters Lists the available values that can be used to filter resources.
definition.parameters.name Describes the functional name of the value, intended for display to the user.
definition.parameters.value Specifies the functional value used in backend logic to apply the filter.
definition.parameters.count Indicates the number of resources currently matching this filter value.

If you want filters for specific resources

Retrieving Search Filters
curl -X GET "https://api-v2.wogeez.com/resources/search/filters?type=DEVICE" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Accept: application/json"

Searching for Resources

This endpoint enables searching for resources based on various criteria. It is designed for use in a search interface where a user can filter, sort, and paginate results.

For example, in a resource management application (devices, scenarios, etc.), a user can search for devices by specifying criteria such as health state, device type, and choosing a sort order.

Search CONNECTED devices
curl -X GET "https://api-v2.wogeez.com/resources/search?connection.state=CONNECTED" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Accept: application/json"

You can combine filters

Search CONNECTED and DISCONNECTED devices
curl -X GET "https://api-v2.wogeez.com/resources/search?connection.state=CONNECTED&connection.state=DISCONNECTED" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Accept: application/json"

It is also possible to perform a full-text search by using the global query parameter

When performing a full-text search, all filters (except pagination and sorting) are ignored. To switch back to classic filtering mode, you must remove the global query parameter. Full-text search is particularly well-suited for mobile applications, where a simple and flexible search interface is often preferred. For example:

Full-text search
curl -X GET "https://api-v2.wogeez.com/resources/search?global=Borne%20Englos" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Accept: application/json"

Note

When performing a full-text search, all filters (except pagination and sorting) are ignored

The response is structured to provide detailed information about the search results, including pagination, sorting, and specific resource data.

Response
{
    "total": 1,
    "page": {
        "page": 1,
        "pages": 1,
        "pageSize": 30
    },
    "sort": {
        "field": "id",
        "direction": "ASC"
    },
    "resources":[...]
}

The JSON structure follows a hierarchical model:

Field Description
total The total number of resources matching the search criteria.
page.page Current page number.
page.pages Total number of pages available.
page.pageSize Number of resources per page.
sort.field Field used for sorting.
sort.direction Sorting direction (ASC for ascending, DESC for descending).

API Reference

For detailed information about search capabilities, please refer to the Swagger API.

Companies

It is also possible to specify the companies to filter. If no company is specified, the search will include all companies associated with the user by default.

Reference

Definition parameter type

Type Description Example
ENUMERATION These values are explicitly listed and often used for filtering [CONNECTED, DISCONNECTED]

ENUMERATION

Enumeration is a concept where a specific field can have a predefined set of possible values. These values are explicitly listed and often used for filtering, categorization, or validation. Enumerations help to standardize input and ensure that only valid options are used. For example, a field like connection.state might have enumerated values such as CONNECTED, DISCONNECTED. By using enumerations, the system can enforce consistency and simplify the filtering process for users.

Soon be available

Additionally, new filter types will soon be available, including date ranges, greater than, less than, and equal to conditions.

Datasheet - Resource

Property Always present Description Type Values
serial X Serial number String
created X Date and time for device creation DateTime
updated X Date and time for device update DateTime
location.name Short text for location String
location.description Long text for location String
geoLocation.latitude Location latitude Double
geoLocation.longitude Location longitude Double
geoLocation.altitude Location altitude Double
connection.connectedSince If device is CONNECTED, date since has been connected DateTime
connection.disconnectedSince If device is DISCONNECTED, date since has been disconnected DateTime
connection.state X Device connection state Enumeration UNKNOWN (if we have never seen device connected), CONNECTED, DISCONNECTED
health Device health state
health.updated X Date and time for device health updated DateTime
health.versionCode X Version code String
health.versionName X Version name String
health.connectedTo Reserved (for future) String
health.mode X Device platform Enumeration SERVER (virtual device run in cloud), EMBEDDED_PLATFORM_COMPUTER (device run on a computer), EMBEDDED_PLATFORM_ANDROID (device run on a Android device), EMBEDDED_PLATFORM_UNKNOWN (device run on unknown platform)
health.hubs.uid X Hub unique id String
health.hubs.label X Hub label String
health.hubs.version X Hub version String
health.hubs.registeredSince X Hub registration String
health.hubs.type X Reserved (for future) Enumeration
health.hubs.battery.health
health.hubs.battery.health.state X (if battery health) Battery health Enumeration COLD, DEAD, GOOD, OVERHEAT, OVER_VOLTAGE, UNKNOWN, UNSPECIFIED_VALUE
health.hubs.battery.health.plugged X (if battery health) Battery plug status Enumeration AC (Alternating Current), DOCK (A station or port that allows a device to connect), USB (Universal Serial Bus), WIRELESS (inductive charging)
health.hubs.battery.health.status X (if battery health) Battery status Enumeration CHARGING, DISCHARGING, FULL, NOT_CHARGING, UNKNOWN
health.hubs.battery.health.status X (if battery health) Battery level % Float 0 to 100%
health.hubs.battery.health.cycle X (if battery health) Battery cycle Integer
health.hubs.devices X A (sub-) device connected to hub
health.hubs.devices.uid X Hub device id String
health.hubs.devices.label X Hub device label String
health.hubs.devices.version X Hub device version String
health.hubs.devices.health.state X Hub device health state Enumeration BOOTING (starting), NOMINAL (all is good), WARNING (can be used, but we have a small problem), DOWN (can't be used, we have a big problem), HIBERNATION (can't be used, for maintenance)
health.hubs.devices.health.message X Hub device health general message String
health.hubs.devices.health.messages X Hub device health messages String
health.hubs.devices.health.messages.key X Hub device health message key String
health.hubs.devices.health.messages.message X Hub device health message message String
health.hubs.devices.health.messages.level X Hub device health message level Enumeration DEBUG, INFO, WARNING, ERROR
health.hubs.devices.capability X Hub device capability
health.hubs.devices.capability.type X Hub device capability type Enumeration SCENARIO, PRINTER, CDN, DATA, IOT, PAYMENT, GENERIC, GENERIC_USB, GENERIC_SERIAL, GENERIC_MONITORING, MEDIA, WEB
health.hubs.devices.capability.modes X Hub device capability modes Enumeration List SCENARIO_EXECUTE, PRINTER_PRINT, CDN_PERSIST, DATA_PERSIST, DATA_SELECT, PAYMENT_CARD_CONTACTLESS, PAYMENT_CARD_PHYSICAL, PAYMENT_CARD_MAGNETIC, GENERIC_BEEP, GENERIC_LED, GENERIC_REBOOT, IOT_DATA_SELECT, IOT_LOCKER_OPEN, MEDIA_IMAGE_HTTP, GENERIC_MONITOR_PRINTER, WEB_PAGE
health.hubs.devices.battery Same as hub
health.hubs.devices.commands X Hub device commands
health.hubs.devices.commands.command X Hub device command name String
health.hubs.devices.commands.title X Hub device command title String
health.hubs.devices.commands.description X Hub device command description String
health.hubs.devices.commands.payload X Hub device command payload Json
health.hubs.devices.commands.arguments X Hub device command arguments