Using GraphQL

🚀

Try our GraphQL Playground

We've included some static documentation below, however GraphQL APIs are traditionally represented through interactive playgrounds. Hover GraphQL Playground

Hover's estimation, proposal, material list, and ordering APIs are built on GraphQL.

GraphQL is a query language for APIs. In contrast to a traditional REST API, GraphQL allows you to retrieve a subset of data associated with an object. This gives developers the flexibility to build their own queries in order to suit their specific needs, without having to be tied down to a specific format and data structure found in a REST endpoint response. In addition to flexibility, GraphQL provides speed and efficiency advantages by passing more compact subsets of data for each request.

GraphQL APIs can still be used very similar to REST APIs, and these endpoints do not require any special libraries or dependencies to be installed in your application.

Making Requests

In contrast to a REST endpoint, GraphQL uses POST for all requests, and all requests must be made to the same endpoint URL.

The Hover GraphQL base url is https://graph.hover.to/graphql.

In order to make a request, you need to make a POST request to the endpoint listed, specify what data you want in the JSON body of the request, and include an Authorization header with the appropriate Access Token.

Some requests will require the use of the current_user_email or current_user_id property as a query string parameter. If you do not include this parameter, or include an invalid parameter, you may see null values within the JSON response. Unless it is specified, assume that all requests require a current_user parameter.

There are two primary ways to make requests in GraphQL:

1. Use a client library that will allow you to setup authorization, graphQL client, and specific queries you want to run.
2. Send GraphQL requests normally in JSON format with "Content-Type": "application/json" in the header, and the GraphQL query in the body of the request formatted as JSON.

Our written GraphQL documentation provides the JSON format for each request. The recommended query structure is included for each request.

The below vidoe will show you how to create a query in GraphQL using out GraphQL playground.

Success and Error Responses in GraphQL

Successful Response

In a successful response, we will return a regular JSON response with the data formatted in the same order of the query sent in the request. You can expect a 200 response code for all requests as long as the query was succesfully constructed.

Common Errors

One common error when hitting the GraphQL API is not having the correct variable or headers. The video below will show you how to quickly get started and find these items to start validating the GraphQL API approach, before needing to create any scripts or code.

Authorization Errors

In the event of an error message, like an authorization error, we will still return a 200 response. This is a key difference with GraphQL endpoints in comparison to REST. To verify that a request was successful, you can reference the JSON response and ensure the errors array is empty. An example of the errors array from a 200 response is listed below.

{
  "errors": [
    {
      "message": "Must be authenticated",
      "path": ["projectManagementOrderDocuments"],
      "extensions": {
        "code": "DOWNSTREAM_SERVICE_ERROR",
        "serviceName": "ehi-api",
        "query": "{\n  projectManagementOrderDocuments(orderDocumentIds: \"08ca6c2e-8793-4129-a751-3952d32a3f95\", productionListId: 6943) {\n    id\n  }\n}",
        "variables": {}
      }
    }
  ],
}

{
  "data": {
    "estimationEstimateGroups": {
      "nodes": [
        {
          "id": 228456,
          "updatedAt": "2020-06-25T08:52:04Z"
        },
        {
          "id": 228457,
          "updatedAt": "2020-06-25T08:52:45Z"
        }
      ]
    }
  }
}

Bad Requests

If the request is malformed, we will return a 400 response and a message body describing the issue. This is typically caused by invalid query parameters or typos in queries.

Here is an example of a 400 response for an invalid query parameter:

{
  "errors": [
    {
      "message": "Cannot query field \"i\" on type \"OrderDocument\". Did you mean \"id\"?",
      "locations": [
        {
          "line": 3,
          "column": 7
        }
      ],
      "extensions": {
        "code": "GRAPHQL_VALIDATION_FAILED"
      }
    }
  ]
}

Here is an example of a 400 response for a syntax error:

{
  "errors": [
    {
      "message": "Syntax Error: Expected {, found :",
      "locations": [
        {
          "line": 1,
          "column": 6
        }
      ],
      "extensions": {
        "code": "GRAPHQL_PARSE_FAILED"
      }
    }
  ]
}