• Documentation and services
• Products
• GraphQL API

GraphQL API

Overview

Graphic Query Language (GraphQL) is a language created for use with APIs. It works as an alternative to REST APIs, allowing you to get data according to your needs. GraphQL gives you autonomy to request the data you want and receive exactly what you asked for through a JSON result.

As GraphQL fetches information differently from traditional APIs, it assists you in filtering data without overfetching. The precise response it provides also gives a better performance to those using GraphQL and makes it easier to use. Another difference from other APIs is that it has a single endpoint.

Having in mind clients who want to request and visualize their data with easy and improved performance, Azion now provides support for GraphQL. You can use the API to maximize the use of your data accessed through Real-Time Metrics, which provides you with real-time access to metrics so you can optimize all of your potential.

You can also check all Azion Observe products: Data Streaming, Real-Time Events, and Edge Pulse.

You don’t need a specific database, framework, or programming language to use GraphQL—you can use it with the code and data you’re already used to. The API relies on queries to access your data and information and filter what you need. Even if you’ve already made a request, you can change, delete, or add more information with a simple modification in your query.

Here’s an example of what a query looks like:

query HttpQuery {
  httpMetrics(
    filter: {
      tsRange: {begin: "2022-03-21T10:10:10", end: "2022-09-23T10:10:10"}
    }
  ) 
  {	
    ts
    geolocCountryName
    geolocRegionName
  }
}

And here’s an example of what the JSON response will look like:

{
    "data": {
        "httpMetrics": [
            {
                "ts": "2022-10-21T15:00:00Z",
                "geolocCountryName": "Canada",
                "geolocRegionName": "Quebec"
            },
            {
                "ts": "2022-10-21T14:00:00Z",
                "geolocCountryName": "Brazil",
                "geolocRegionName": "Parana"
            }
        ]
    }
}

By using queries in Azion GraphQL API, you can request data through a time interval. The API will fetch your data according to a pre-defined interval of minutes, hours, or days.

Using GraphQL

1. First Steps
   1.1 Accessing GraphQL API
   1.2 Accessing GraphQL playground
2. Queries
3. Features
   3.1. Datasets
   3.2. Filtering
   3.3. Sorting
   3.4. Pagination
4. Limits
5. Error Responses

1. First Steps

Learn how to access Azion GraphQL API and the GraphQL playground.

1.1 Accessing GraphQL API

To use GraphQL API with API platforms such as Postman and Insomnia, you first need authentication to ensure requests access data securely. This authentication occurs through Tokens.

To create a Token, you can follow two different paths:

• Use Azion API platform.
• Use Real-Time Manager (RTM).

The first option is to create a Token through the Azion API platform. You can go to Token and run your request.

The second option is to create a Personal Token through Azion configuration interface, Real-Time Manager (RTM). This option is more suitable for use with APIs due to the possibility of creating a long-lived token. See the Personal Tokens documentation page to create one.

When creating a Personal Token, you’ll have to set an expiration date. For use with APIs, it’s recommended to set a longer expiration date, such as 90 days or 1 year. In that case, make sure you take necessary precautions to ensure your project’s security.

After creating your Personal Token, head to the API platform you’ll be using and include the Azion GraphQL API endpoint in your request: https://api.azionapi.net/metrics/graphql

1.2 Accessing GraphQL playground

You can use Azion GraphQL built-in playground to write, validate, and test GraphQL queries. Using the playground can help you become more familiar with the API and the use of queries in a visual and quick manner.

To interact with the GraphQL playground, you first need to log in to RTM. If you haven’t created an account, see the Creating an account on Azion documentation page.

After successfully logging in to RTM, go to https://api.azionapi.net/metrics/graphql and interact with the GraphQL playground.

2. Queries

Queries are the starting point to begin consulting information as you use a query to request information from a database. The GraphQL API relies on queries to fetch values and send the requested data as a response with a similar format in a JSON file.

The use of queries enables requesting and fetching specific data. This means you can get a response to your request even with a small query if you don’t want to see data that isn’t essential at that moment. Using queries also means you get faster responses, as the GraphQL API doesn’t need to fetch unnecessary amount of data.

Queries also make it easier for you to add or delete information from your request. For example, if you request data for httpMetrics:

query HttpQuery {
  httpMetrics(
    limit: 2
    filter: {
      tsRange: {begin:"2022-10-20T10:10:10", end:"2022-10-23T10:10:10"}
    }
  ) 
  {	
    ts
    sourceLocPop
    requests
  }
}

And decide you want to add idnsQueriesMetrics to your request, you can add a similar query, only changing the dataset you want to fetch, and run another request:

query IdnsQuery {
  idnsQueriesMetrics(
    limit: 2
    filter: {
      tsRange: {begin:"2022-10-20T10:10:10", end:"2022-10-23T10:10:10"}
    }
  ) 
  {	
    ts
    sourceLocPop
    requests
  }
}

By using queries, your request and responses also become more organized. Due to GraphQL’s ability to adapt, you can make several calls to the API and still receive only the data you requested in an organized JSON result.

Using the GraphQL API and its features also improve your performance.

3. Features

GraphQL features consist of datasets, filtering, sorting, and pagination. The features provide easy access to your data, and using and combining the available features creates more personalized and specific queries to request the exact information you need.

The next sections will detail each available feature of GraphQL and how to use them.

3.1 Datasets

Azion GraphQL API uses defined datasets to indicate what requests you can run through queries and fetches data from Real-Time Metrics. They consist of organized tables informing your data.

Find each available dataset and what they request next:

To learn which fields are available for each dataset, you can run an Introspection Query to consult metadata. Find out more on the Consulting metadata with GraphQL API guide.

While using datasets, you’ll be querying for data within a time interval and you’ll receive it in the form of graphs related to that dataset.

To specify you want to aggregate data with a time interval, add the aggregate operator in your query along with the group_by field. For example, the following query aggregates data:

query IdnsQuery {
  idnsQueriesMetrics(
    limit: 10
    aggregate: {sum:requests}
    groupBy: [ts]
    filter: {
      tsRange: {begin:"2022-10-20T10:10:10", end:"2022-10-23T10:10:10"}
    }
  ) 
  {	
    ts
    sum
  }
}

Find out more on how to aggregate data with the Consulting aggregated data with the GraphQL API guide.

It’s important to note you’ll receive data according to a time range defined through an adaptive resolver. Currently, there are three possible intervals to fetch your results: minute, hour, and day.

Each query interval is used according to the following definitions:

• Minute: used for queries in the interval of up to 3 days.
• Hour: used for queries in the interval of 3 and 60 days.
• Day: used for queries in the interval of over 60 days.

To successfully receive data as a response, you must inform a time interval either through a tsRange or a tsGt + tsLt field in your queries with a valid date and time format. If you use tsRange, you’ll receive data greater than or equal to or less than or equal to that specific interval, including the beginning and ending date you’ve informed.

Use the following example as a basis to apply a tsRange in your request:

tsRange: {begin:"2022-06-23T09:10:10", end:"2022-06-23T16:10:10"}

If you use tsGt + tsLt, you’ll receive data greater than or less than that specific interval, not including the beginning and ending date you’ve informed.

Use the following example as a basis to apply a tsGt + tsLt in your request:

{

  "tsGt": "2022-07-22T10:10:10",

  "tsLt": "2022-09-19T10:10:10"

}

Defining and informing a time range interval in your queries is important to fetch data from the available datasets of the GraphQL API and continue running requests with the other available features.

3.2 Filtering

With filtering parameters, responses returned by your queries can be more accurate to your set of data. You can use filtering with any available field in the dataset you’re consulting.

As requesting complex or a large amount of data can cause responses to get noisy and complicate its use, filtering queries helps with getting exact and direct data from your requests. For example, if you’re using the following query to request httpMetrics:

query HttpQuery {
  httpMetrics(
    limit: 10
    filter: {
      tsRange: {begin:"2022-10-20T10:10:10", end:"2022-10-23T10:10:10"}
    }
  ) 
  {	
    ts
    sourceLocPop
  }
}

You can filter the query by requesting data specific to the sourceLocPop field:

query HttpQuery {
  httpMetrics(
    limit: 10
    filter: {
      tsRange: {begin:"2022-10-20T10:10:10", end:"2022-10-23T10:10:10"}
      sourceLocPop: "lax-bso"
    }
  ) 
  {	
    ts
    sourceLocPop
  }
}

You can feel free to update your request to use a field of your interest within the fields of the dataset you’re consulting.

3.3 Sorting

The sorting feature lets you organize and sort the received data of a dataset according to the event’s order. For example, if you’re receiving the host field data as a response to your API request, you can sort the data to receive it in an ascending order (ASC) — from oldest record until most recent record.

To use the ascending order sorting feature, add orderBy in your query and the field you want to sort. For example:

{
    orderBy: [host]
}

If you want to sort the data according to the timestamp of a field, you can order it in ascending order (ASC) or descending order (DESC). Although ASC is the default sort for all fields in the dataset, you can only use DESC order with the timestamp (TS) field. For example:

{
    orderBy: [TS_DESC]
}

3.4 Pagination

Pagination is a feature designed to help you decide where you want your results to begin from and how many results you want to see. Currently, Azion GraphQL API uses offset and limit pagination to provide the feature.

Using pagination can be useful when you get a large number of data in response to your API request. You can use the feature by setting offsets and limits. This way, the API knows it needs to return data within the specific range you’ve set.

The offsets parameter sets the number of records you want to skip in your data response, and the limits parameter sets the number of results you want to receive.

Setting offset and limit parameters isn’t mandatory. In case you don’t set the parameters, GraphQL API automatically sets the offset for 0 and the limit for 10.

See the following example on how to set offset and limit parameters:

query HttpQuery {
  httpMetrics(
    offset: 15
    limit: 30
    filter: {
      tsRange: {begin:"2022-10-20T10:10:10", end:"2022-10-23T10:10:10"}
    }
  ) 
  {	
    ts
    sourceLocPop
  }
}

The offset is set for 15, meaning your response will start with the 16th result, and the limit is set for 30, meaning your response will give you a total of 30 results. In this case, you’ll receive a response from the 16th result until the 45th result.

If your data is constantly updated, using pagination may cause missing or duplicate data when you run more than one request using the feature.

4. Limits

To keep GraphQL API working with enhanced performance, the API has predetermined limits you must pay attention to. See which are these limits next.

Request limit

You can run up to 120 request per minute for each IP address. In case you surpass the standard request limit, the API will return an Error Response message informing the issue. To continue using the API, wait for the time limit to pass and run the request again.

Query rows limit

You can query up to 10,000 rows per query. The limit field in your query controls this restriction, and you can set it as you desire as long as it doesn’t surpass the the GraphQL API’s limit. If you surpass it, the API will return an Error Response message informing the issue.

Selected fields limit

When you’re querying for datasets’ fields, the maximum value of selected fields is of 35 fields per query. If you surpass the fields’ limit, the API will return an Error Response message informing the issue.

See the Error Responses section for more details on the messages regarding limit errors.

5. Error Responses

The GraphQL API returns standard HTTP status codes to indicate an error. Whenever you receive a status code while trying to run a request, you’ll also receive an error message. These errors relate to authentication, limits, access, or query and GraphQL construction issues.

You can receive the following status codes and error messages in a query format:

If you receive any of the described Error Responses, see the rest of the GraphQL API documentation to find specifications and correct your request.

Didn’t find what you were looking for? Open a support ticket.