Introduction to the New Relic GraphQL API

New Relic's GraphQL is an efficient and flexible query language for your API. It gives you the power to request exactly the data you need, without over-fetching or under-fetching. While typical REST APIs require loading from multiple URLs, GraphQL APIs get all the data your app needs in a single request. GraphQL also makes it easier to evolve APIs over time and enables powerful developer tools.

If your account hosts data in the EU data center, ensure you are using the proper API endpoints for EU region accounts.

Use the GraphQL API explorer

New Relic provides you with a powerful GraphiQL tool to explore the API with embedded schema definitions at https://api.newrelic.com/graphiql.

For more information, check out the New Relic University tutorial Intro to New Relic GraphQL API or view the full online course New Relic APIs.

Authentication

To get started with the New Relic GraphQL API explorer, you must have a New Relic API key. If you do not already have one:

GraphQL endpoint

The New Relic GraphQL API has a single endpoint:

https://api.newrelic.com/graphql

To access the endpoint, use the following cURL command:

curl -X POST https://api.newrelic.com/graphql \
-H 'Content-Type: application/json' \
-H 'API-Key: YOUR_API_KEY' \
-d '{ "query":  "{ requestContext { userId apiKey } }" } '

New Relic GraphQL tutorials

With the New Relic GraphQL API, you can use GraphQL to:

GraphQL terminology

The New Relic GraphQL server explicitly defines the graph structure of the New Relic API. The following keywords are common to all GraphQL servers. Use these keywords to help build and understand your own queries. In addition:

Term Definition
Queries

Queries are basic requests that are intended to only fetch data, without any additional actions. Queries in GraphQL are not static, meaning that you can ask for more or less data depending on your needs. For each query, you can specify exactly what data you want to retrieve, as long as it is supported by the schema.

Mutations

Mutations are requests that are intended to have additional actions, such as creating data or updating data on a server. Mutations require the keyword mutation, as well as the name of the mutation.

Type

Data in GraphQL is organized into types. Types can be scalars (like strings, numbers, or booleans) or object types.

An object type is a custom type made up of a collection of fields. For example, an object type called User may represent a User in a system.

Field A field represents a piece of information on an object type that can be queried. Fields can be scalars, lists, or objects. For example, a User object type could have a string field called name.
Interface An interface is an abstract type that represents a collection of common fields that other object types can implement.

Make queries with the New Relic GraphQL API

You can make queries with the New Relic GraphQL API explorer. The explorer provides built-in schema definitions and features, including auto-complete and query validation.

In GraphQL, you ask for specific information in the graph structure of New Relic's data. You can follow the nodes of the graph to query exactly the data that you want.

New fields are added seamlessly, and old fields can be marked as deprecated, which removes them from documentation and allows an eventual, graceful shutdown of that field.

Query account a New Relic user can access

You can query for the name of an account that an actor (a New Relic authorized user) has access to:

query {
   actor {
      account(id: YOUR_ACCOUNT_ID) {
         name
      }
   }
}

The response will mirror the query structure you defined in the request, making it easy to ask for the specific data that you want.

{
  "data": {
      "actor": {
         "account": {
            "name": "Data Nerd"
         }
      }
   }
}
Query user, account, and NRQL in one GraphQL request

The graph structure shows its capabilities when queries become more complex. For example, you can query for user information, account information, and make a NRQL query with one request. With REST API, this would take three different requests to three different endpoints.

query {
   actor {
      account(id: YOUR_ACCOUNT_ID) {
         name
         nrql(query: "SELECT * FROM Transaction") {
            results
         }
      }
      user {
         name
         id
      }
   }
}

For more help

Recommendations for learning more: