Skip to main content

APIs References

Overview​

Clea provides a complete set of APIs to interact and manage aspects of the platform and the data it contains. All the main features of Clea are available through the Public APIs of the platform components.

Different types of APIs are available depending on the data or functionality you want to access:

  • Clea Portal: Regarding the data managed by the Clea Portal, it is possible to use the queries made available in the GraphQL language. The information that you can access is, for example, the list of Appliances, the detailed data of the single Appliances, the information about users and roles, and others.
  • Edgehog: Suppose you want to access the device management features made available by Edgehog. In that case, you can use its GraphQL APIs that allow you to perform monitoring and fleet operations such as update campaigns and others.
  • Astarte: As far as the data sent by the Appliances and the commands you need to send to the machines are concerned, it is possible to interact directly with the Astarte platform using the Astarte REST API.

These references will help developers integrate Clea services inside their workflow and company applications.

Clea Portal GraphQL APIs​

The GraphQL APIs are self-describing and easy to understand. You can download the complete query schema with any GraphQL API interaction tool, such as graphql-ci.

The URL address of the Clea GraphQL API is different depending on the Tenant.

Here are some examples of the most relevant GraphQL queries.

Login​

mutation Login($input: LoginInput!) {
  login(input: $input) {
    token
  }
}

You can use the credentials of a Clea user to login. The user will be able to read information from Clea, according to the permissions set for him via the Clea Portal interface.

Appliances List​

query GetAppliances {
  appliances(filter: { assigned: true }) {
    id
    name
    serial
    tags
  }
}

Single Appliance Data​

query GetAppliance($id: ID!) {
  appliance(id: $id) {
    id
    name
    serial
    tags
    device {
      deviceId
      realm
      baseApiUrl
      online
      availableApplications {
        id
        authToken
      }
    }
  }
}

User and Preferences​

query GetViewer {
  viewer {
    id
    name
    email
    roles {
      id
      name
    }
    preferences {
      language
    }
  }
}

Edgehog GraphQL APIs​

Edgehog also provides GraphQL API interfaces. As stated earlier, these are self-describing, and you can download the complete query schema with any GraphQL API interaction tool, such as graphql-ci.

You can find more information on interacting on devices through Edgehog's API features on the official Edgehog documentation. Edgehog's GraphQL APIs are also described on this useful API Reference page.

Astarte REST API​

Regarding the data sent and the commands to be sent to the machines, it is possible to interact directly with the data contained in the Astarte platform on which Clea relies.

For complete documentation of the Astarte APIs, you can consult the following pages:

From the GraphQL queries described in the previous section, it is possible to get the data needed to make the API calls that operate on the Astarte interfaces to request data or send commands to the machine.

You can take the base URL and the authorization token values from the GraphQL query that provides the appliance data:

  • The base URL is baseApiUrl
  • The authorization token authToken can be obtained from the setup-app entry in the availableApplications.

Thanks to these data, it is possible to make REST calls to Astarte APIs. It is also necessary to know the Astarte interfaces used by devices to exchange data for completing the necessary API calls.

For example, the queries to be used will have the form:

${baseApiUrl}/appengine/v1/${tenantName}/devices/${deviceId}/interfaces/${interfaceName}${path}

GET calls can be used to get the data, and POST calls can be used to send it.