Skip to main content

Getting Started with GraphQL

info

This is a technical guide on how to query Relay API using GraphQL clients. If you're looking for no-code integrations, learn more here.

GraphQL queries are executed by making POST HTTP requests to the following endpoint:

https://api.relaywireless.com/graphql

Each query starts with one of the objects listed in GraphQL Schema, which serves as the entry point for all queries defined by the schema.

GraphQL queries function similarly to a GET request in REST.

Basic Query Structure​

GraphQL queries follow this pattern:

query {
  resourceName {
    field1
    field2
    nestedResource {
      nestedField1
      nestedField2
    }
  }
}

Making Your First Query​

Using curl​

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"query": "{ status }"}' \
  https://api.relaywireless.com/graphql

Using a GraphQL Client​

// Using Apollo Client
import { ApolloClient, InMemoryCache, gql } from "@apollo/client";

const client = new ApolloClient({
  uri: "https://api.relaywireless.com/graphql",
  cache: new InMemoryCache(),
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});

// Make a query
client
  .query({
    query: gql`
      {
        status
      }
    `,
  })
  .then((result) => console.log(result));
Pro Tip

You don't have to create your own GraphQL queries. You can also use Relay's REST API that exposes some predefiend queries. Learn More About the REST API

Available Queries​

The API provides the following main queries:

  • status: Get the API status
  • iotRewardShares: Get IoT reward shares
  • mobileRewardShares: Get Mobile reward shares
  • echo: Echo a message (for testing)

For detailed information about the available fields and types, refer to the GraphQL Schema Documentation.

Example Queries​

  1. Get IoT Reward Shares:

    query {
      iotRewardShares(
        first: 10
        startPeriod: "2024-01-01T00:00:00Z"
        endPeriod: "2024-01-31T23:59:59Z"
      ) {
        nodes {
          hotspotKey
          amount
          beaconAmount
          dcTransferAmount
          witnessAmount
          startPeriod
          endPeriod
          rewardType
          unallocatedRewardType
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }

  2. Get Mobile Reward Shares:

    query {
      mobileRewardShares(
        first: 10
        startPeriod: "2024-01-01T00:00:00Z"
        endPeriod: "2024-01-31T23:59:59Z"
      ) {
        nodes {
          hotspotKey
          amount
          baseCoveragePointsSum
          basePocReward
          baseRewardShares
          boostedCoveragePointsSum
          boostedPocReward
          boostedRewardShares
          cbsdId
          dcTransferReward
          discoveryLocationAmount
          startPeriod
          endPeriod
          entity
          locationTrustScoreMultiplier
          matchedAmount
          oracleBoostedHexStatus
          ownerKey
          pocReward
          rewardType
          seniorityTimestamp
          serviceProviderAmount
          serviceProviderId
          spBoostedHexStatus
          speedtestMultiplier
          subscriberId
          subscriberReward
          unallocatedRewardType
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }

Using Variables​

Variables make your queries more reusable:

query GetRewardShares($first: Int!) {
  mobileRewardShares(first: $first) {
    nodes {
      hotspotKey
      amount
      rewardType
    }
  }
}

Variables JSON:

{
  "first": 5
}

Pagination​

All list queries support cursor-based pagination:

query {
  iotWitnessIngestReports(first: 10) {
    nodes {
      hotspotKey
      dataRate
      frequency
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

To get the next page, use the endCursor from the previous query:

query {
  iotWitnessIngestReports(first: 10, after: "previous-end-cursor") {
    nodes {
      hotspotKey
      dataRate
      frequency
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Best Practices​

  1. Request Only What You Need

    # Good
    query {
      mobileRewardShares(first: 10) {
        nodes {
          hotspotKey
          amount
        }
      }
    }

    # Bad - requesting unnecessary fields
    query {
      mobileRewardShares(first: 10) {
        nodes {
          hotspotKey
          amount
          rewardType
          startPeriod
          endPeriod
          serviceProviderId
          # ... many more fields
        }
      }
    }

  2. Use Fragments for Reusable Fields

    fragment RewardDetails on MobileRewardShare {
      hotspotKey
      amount
      rewardType
      startPeriod
      endPeriod
    }

    query {
      mobileRewardShares(first: 10) {
        nodes {
          ...RewardDetails
          serviceProviderId
        }
      }
    }

Tools and Resources​