# Usage remote.it is in the process of making available all functions in graphQL and will be eventually deprecate the REST-API. This documentation provides the REST-API where the function is not available via graphQL. ## Remote.it Insomnia Collection We have developed an example set of GraphQL queries and mutations in a collection that you can import directly into insomnia to get started. You will still need to install the authentication plug-in [here](/developer-tools/api/using-developer-tools.md#add-the-plugin-to-insomnia) and create your access keys in your account before getting started. ``` $ git clone https://github.com/remoteit/code_samples.git ``` ## What is GraphQL? GraphQL is a data query language for API's, developed by Facebook in 2012 before being publicly released in 2015. GraphQL provides an alternative to the REST API. For more information on GraphQL, learn on the official GraphQL website [**here.**](https://graphql.org/) ## How to Access GraphQL `https://api.remote.it/graphql/v1` Continue through this documentation to learn about our schema and some useful examples. remote.it authentication uses HTTP Request Signature; more on Authentication can be found [here](/developer-tools/authentication.md). ### GraphQL Clients (Developer Tools) These are some of the most popular developer tools used with GraphQL API's which you can use to explore the schema. * [**Insomnia**](https://insomnia.rest/graphql/) * [**Postman**](https://www.getpostman.com/) * [**GraphiQL**](https://www.electronjs.org/apps/graphiql) * [**Altair**](https://altair.sirmuel.design/) We provide some basic setup and usage for the Insomnia client [here](/developer-tools/api/using-developer-tools.md). You can view our visual schema reference [**here.**](https://api.remote.it/graphql/v1/doc) ### **Schema Definitions** GraphQL endpoint supports introspection queries via the \_\_schema query**.** There is also a visual version of the schema available at {% hint style="info" %} #### We recommend using a GraphQL client (Developer Tools) to introspect and explore the schema. Configure your GraphQL client to use the API endpoint: `https://api.remote.it/graphql/v1` {% endhint %} Schema convention is to use upper camel case for object types and lower camel case for property names. Note that these objects and parameters are continually enhanced. Please use your IDE for the most up to date schema. The changes are designed to be non-breaking by adding rather than deleting or changing existing definitions. Basic types are: * ID (similar to the string type but used for object IDs) * String * Int * Float * Boolean * DateTime (ISO 8601 format Date String) ## Queries Queries are requests which read the data and will not change the data. All queries will be in context of the user associated with the access key and secret. The usage examples include a variable section which will need to accompany the query or alternatively, you can put the values inline. ### Fetching updates If you're working on building an application which display data and you want the status information to update (near) realtime, use the [webhook](/developer-tools/webhooks.md). To prevent excessive usage of our API, we recommend that you be mindful about your implementation. **Do's:** * Register a programmatic [webhook](/developer-tools/webhooks.md) and get updates for status changes on your devices. When you detect changes, update the device information **Dont's:** * Poll updates for each device. There should never be a reason to do this, unless in small cases and your application might get rate limited. See above tactics to implement this better. ## Mutations Mutations are requests which update data. All mutations are in context of the user associated with the access key and secret. In the case where we do not have the functionality supported, the REST-API examples are provided. These will be updated from time to time as remote.it migrates to support graphQL only. ## Pagination The list responses from the devices and event log queries return paginated results. We implement a pagination model with `from`/`after` and `size` pagination arguments. Responses can return `hasMore`, `last` and `total` . If the `hasMore` response returns true, this indicates do another fetch. In this case, the `from` will increment to 1001 to fetch the next set. You could also determine this by iteration until you get to the `total`. Size is limited to 1000 max in each return. **Filter** | Attribute | Data Type | Description | | ----------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | size | Int | Number of records to return in result of items (Max value is 1000) | | from | Int | Where to start return of list if there are more records than the size | | last | String | Primary ID of the item returned to start in the return (If this is passed, from is ignored, however it may not return if the rest of the filters to not include this item) | | sort | String | attribute to sort the item list return and append a space + asc or desc for ascending and descending | | additional filters are available per collection | | See documentation in Schema for complete list as this is updated. | ```javascript #Query query getDevices($size: Int, $from: Int, $sort: String) { login { devices(size: $size, from: $from, sort: $sort) { total hasMore last items { id name hardwareId created services { id name } } } } } #Variables { "size": 1000, "from": 0, "sort": 'name', } ``` Result Response ```bash { "data": { "login": { "devices": { "total": 1200, "hasMore": true, "items": [ { "id": "8X:XX:XX:00:29:01:8e:ed", "name": "bento", "hardwareId": "dc:a6:32:19:8b:a3-xWoYf46uJ6QdtPXTloLb", "created": "2019-12-20T22:13:46.000Z", "services": [ { "id": "8X:XX:XX:00:29:01:8e:ed", "name": "ssh service" } ] }, ... ] } } } } ``` **Response List Attribute** | Attribute | Data Type | Description | | --------- | --------- | -------------------------------------------------------------------------------------------------- | | total | Int | Number of records that exist based on the filter criteria of query | | hasMore | Boolean | Indicates if you should make an additional request to fetch more records if you want the full list | | last | String | ID of the last item in the returned list. | | | | | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.remote.it/developer-tools/api/usage.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.