Dashboards API migration: from Insights API to Nerdgraph

In case you haven’t heard, NerdGraph is New Relic’s unified API in a GraphQL flavor. The new dashboards API follows this unified approach and is exposed through NerdGraph for user consumption.

Why a new dashboards API?

Dashboards in New Relic embrace the entity concept and are now an entity in New Relic’s entity ecosystem. Dashboards can now connect with any other type of entity for better observability solutions, which opens the door to endless opportunities we would like you to benefit from.

At the same time, we have built new features for dashboards:

From REST endpoints to GraphQL queries/mutations

One of the main benefits from a GraphQL API is that it provides a complete and understandable description of the APIs' data. By using NerdGraph GraphiQL explorer, you can discover GraphQL types and fields, along with a brief explanation.

We want to facilitate your migration from the Insights API to the new New Relic One dashboards API. Find below some examples that illustrate how the old REST endpoints map to the new GraphQL queries or mutations.

List (GET) -> entitySearch query

Dashboards in New Relic One embrace the concept of entity. They are now another entity in New Relic’s entity ecosystem.

  • You can list all the dashboard entities you have access to:
{
  actor {
    entitySearch(queryBuilder: {type: DASHBOARD}) {
      results {
        entities {
          ... on DashboardEntityOutline {
            guid
            name
            accountId
          }
        }
      }
    }
  }
}
  • You can list all the dashboards by name:
{
  actor {
    entitySearch(queryBuilder: {name: "My dashboard"}) {
      results {
        entities {
          ... on DashboardEntityOutline {
            guid
            name
            accountId
          }
        }
      }
    }
  }
}
  • You can list all the dashboards by the creator’s email:
{
  actor {
    entitySearch(queryBuilder: {type: DASHBOARD, tags: {key: "createdBy", value: "email@domain.com"}}) {
      results {
        entities {
          ... on DashboardEntityOutline {
            guid
            name
            accountId
          }
        }
      }
    }
  }
}
  • You can list all the dashboards by the creator’s userId:
{
  actor {
    entitySearch(query: "type = 'DASHBOARD' and ownerId = "2357322") {
      results {
        entities {
          ... on DashboardEntityOutline {
            guid
            name
            accountId
          }
        }
      }
    }
  }
}

Show (GET) -> entity query

In order to get information on a dashboard, all you need is to provide its unique entity identifier or entity GUID. Then you can access all the dashboard properties that you are interested in by adding them in the GraphQL query.

In the example below we are only interested in the entity GUID and the name of our dashboard.

{
  actor {
    entity(guid: "MY_DASHBOARD_GUID") {
      ... on DashboardEntity {
        guid
        name
      }
    }
  }
}

Create (POST) -> dashboardCreate mutation

Operations that mutate the state of the system are mutations in GraphQL APIs. You can create a dashboard by providing the required input for the dashboardCreate mutation. Although GraphQL APIs aim to be self-explanatory, Nerdgraph docs can help you with some information about the fields, like the doc about how to build dashboard widgets.

The example below is not complete but can give you an understanding of how the mutation looks like. Try it out using the NerdGraph GraphiQL explorer.

mutation {
  dashboardCreate(
    accountId: 1, 
    dashboard: {
      name: "My dashboard",  
      pages: [
        {
          name: "Errors page", 
          widgets: {}
        }
        {
          name: "Logs page", 
          widgets: {}
        }
      ], 
      permissions: PUBLIC_READ_ONLY
    }) {
    entityResult {
      name
      guid
      updatedAt
      createdAt
    }
    errors {
      description
      type
    }
  }
}

Update (PUT) -> dashboardUpdate mutation

The dashboardUpdate mutation allows you to update an existing dashboard by providing the existing dashboard GUID and the new configuration. Similarly to creating a dashboard, the mutation tries to be self-explanatory, but you can look up the doc about how to build dashboard widgets.

The example is not complete but it can give you an understanding of how the mutation looks like. Try it out using the NerdGraph GraphiQL explorer.

mutation {
  dashboardUpdate( 
    guid: "MY_EXISTING_DASHBOARD_GUID",
    dashboard: {
      name: "My dashboard",  
      pages: [
        {
          name: "Errors page", 
          widgets: {}
        }
        {
          name: "Logs page", 
          widgets: {}
        }
      ], 
      permissions: PUBLIC_READ_ONLY
    }) {
    entityResult {
      name
      guid
      updatedAt
      createdAt
    }
    errors {
      description
      type
    }
  }
}

Delete (DELETE) -> dashboardDelete mutation

The dashboardDelete mutation allows you to delete an existing dashboard by providing its entity GUID.

mutation {
  dashboardDelete {
    status
    errors {
      type
      description
    }
  }
}

Errors as first class citizens

As you might have noticed, all dashboard mutations offer you a way to ask for errors when being executed. This means that you can perform your dashboard mutations and check the response in order to detect potential issues. Every error has a type and a description to help you identify what’s the source of the problem.

mutation {
  dashboardMutation(guid: "MY_EXISTING_DASHBOARD_GUID") {
    mutationResult {
      result
    }
    errors {
      description
      type
    }
  }
}

If you need more help, check out these support and learning resources: