DataPacket GraphQL API

July 22, 2024: servers query changes

Field changes

• The status field has been deprecated and replaced with a new field called statusV2. The statusV2 field provides a more accurate representation of the server’s production status.

Input argument changes

• The field changes are also reflected in the input arguments. The serverStatus_in filter has been deprecated, and it is recommended to use the new serverStatusV2_in filter for filtering based on the server’s status.

• The tags_each input argument has been renamed to tag_value. The old tags_each argument name has been deprecated.

• A new argument called tag_key has been introduced to filter based on tag keys.

To get an introduction to GraphQL, you can use the official documentation, or learn with the How to GraphQL tutorials.

GraphQL requests can be sent via HTTP POST or HTTP GET requests. POST requests sent with the Content-Type header application/json must have a POST body in the following JSON format:

{
  "query": "...",
  "variables": { "myVariable": "someValue", ... }
}

GET requests must be sent in the following format. The query and variables are sent as URL-encoded query parameters in the URL.

https://api.datapacket.com/v0/graphql?query={...}&variables={...}

In either request method (POST or GET), only a query is required. variables is only required if the query contains GraphQL variables.

There are many GraphQL clients available for different platforms.

The easiest way to start (but not the most convenient) is to use cURL. For example, you can use the following command to get your account information:

curl -X POST 'https://api.datapacket.com/v0/graphql' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{"query":"query account { account { name email } }"}'

GraphQL requests are of two types: queries and mutations.

Queries are read-only and do not change the system's state. Only requested query fields are returned in the response. Fields ending with ! are non-nullable. If the field is not available, the query will fail. The response is a JSON object and the requested data is returned in the data field.

Mutations are used to change data and must be sent via POST request.

You can send multiple queries and mutations in a single request. They will be executed in the order they are specified in the request.

Input variables

Use variables to pass arguments to a query or mutation. Define variables in the request body and reference them in the query or mutation. Fields suffixed with ! are required.

For example, the performServerPowerAction mutation requires the server and status fields. To turn the DP-12345 server on, you can use the following query:

curl -X POST 'https://api.datapacket.com/v0/graphql' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
        "query":"mutation performServerPowerAction($input: PerformServerPowerActionInput!) { performServerPowerAction(input: $input) { server { name } } }",
        "variables": { "input": { "server": { "name": "DP-12345" }, "action": "ON" } }
      }'

The logical relation between input parameters for filtering is always AND. When specifying more than one value for a filter parameter ending with *_in, the values in the array have the OR relation.

For example, to get IPMI IP addresses of all your servers in London or Amsterdam with power status ON, you would call the following query:

 curl -X POST 'https://api.datapacket.com/v0/graphql' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
       "query":"query servers($input: PaginatedServersInput) { servers(input: $input) { entriesTotalCount currentPageIndex entries { name network { ipmi { ip } } } } }",
       "variables": { "input": { "pageIndex": 0, "pageSize": 20, "filter": { "location_in": ["London", "Amsterdam"], "powerStatus_in": ["ON"] } } }
      }'

Queries and mutations can return errors. If an error occurs, the response will contain an errors field with a list of errors. Each error has a message field with a human-readable error message and a code field with an error code. List of error codes can be found in the Error section.

Errors typically return HTTP status code 200. Malformed requests will also return an errors field along with HTTP status code 400.

GraphQL errors are returned in the following format:

{
  "errors": [
    {
      "message": "Error message",
      "extensions": {
        "code": "ERROR_CODE"
      }
    }
  ]
}

All results are paginated. You can specify the number of results per page and the page number using pageSize and pageIndex input variables. The maximum number of results per page is 50. The total number of results is returned in the entriesTotalCount field.