Differentiating a GraphQL query from a compatible REST API request

[kettanaito]

I'd like to discuss how to reliably differentiate a GraphQL query from a REST API request that has a compatible body/query string structure. This originates from #489.

The issue

In order for graphql.* handlers to work, they determine if the captured HTTP request is compatible with the GraphQL specification, specifically:

• It's a GET request with a query query string parameter.
• It's a POST request with a query property in its JSON body.

Upon retrieval, the query is parsed using the graphql package to determine if the query itself is valid against the GraphQL specification. If there's no query, or it's invalid, the request is not captured by the graphql.* handler and is bypassed.

The issue arises from regular REST API requests that also have the query but are not meant to be GraphQL queries. For example, you may have the following request:

POST /search
{
  "query": "dogs"
}

Since the aforementioned request satisfies one of the predicates for a graphql.* handler, MSW will attempt to parse its body.query string as a GraphQL query declaration string. That operation will fail, and the exception will be thrown (?).

Specification

There's nothing in the GraphQL specification that would reliably tell apart a GraphQL query and a seemingly compatible REST API request.

One of the solutions that may help:

• If a GraphQL query had a specific request header.
• Using a graphql.operation handler to limit requests interception to a certain endpoint. This way the consumer explicitly declares a certain endpoint as a GraphQL endpoint, so MSW can assume that requests to that endpoints are either valid or invalid GraphQL queries, but not regular REST API requests.

[kettanaito]

The parsing of a GraphQL query body isn't a reliable way to determine a GraphQL request, because a failed parsing can indicate two things:

1. It's not a valid GraphQL query.
2. It's a non-GraphQL request.

In the first case, the query error should be surfaced to the user. That's what would happen when communicating with an actual GraphQL server: it would throw an exception indicating what's wrong with the query is received. Since MSW acts as a "server", I find it a nice touch to be able to surface those parsing errors to the user. This is especially useful when there's no actual GraphQL server and people are using the mock-first approach in development.

However, since a failed query parsing may also indicate a non-GraphQL request, surfacing the parsing error requires extra effort on the library's side. This again comes down to figuring out if the query/exception is related to an invalid query or not.

[kettanaito]

With the latest changes we've added an internal parseGraphQLRequest function that attempts to parse any request as a GraphQL request gracefully:

msw/src/utils/internal/parseGraphQLRequest.ts

Line 22 in 87ea5db

function getGraphQLQuery(request: MockedRequest<any>): string | null {

It can reliably determine if a given GET/POST request is a valid GraphQL request. However, it cannot distinguish if the request is not GraphQL-compatible (i.e. a POST request with a query body key not meant for GraphQL), or contains an invalid GraphQL operation definition (i.e. res.body.query is an invalid GraphQL query due to a syntax validation).

We can either extend that parseGraphQLRequest function to return different error instances (i.e. Error or SyntaxError) or create another function dedicated just to that.

[kettanaito]

The GraphQL requests differentiation has been improved with the introduction of the parseGraphQLRequest utility:

msw/src/utils/internal/parseGraphQLRequest.ts

Lines 139 to 172 in 655c93f

	/**
	* Determines if a given request can be considered a GraphQL request.
	* Does not parse the query and does not guarantee its validity.
	*/
	export function parseGraphQLRequest(
	request: MockedRequest<any>,
	): ParsedGraphQLRequest {
	const input = getGraphQLInput(request)
	if (!input || !input.query) {
	return undefined
	}
	const { query, variables } = input
	const parsedResult = parseQuery(query)
	if (parsedResult instanceof Error) {
	const requestPublicUrl = getPublicUrlFromRequest(request)
	// Encountered a matching GraphQL request that is syntactically invalid.
	// We may consider getting the parsing error and propagating it to the user.
	console.error(
	`[MSW] Failed to intercept a GraphQL request to "${request.method} ${requestPublicUrl}": cannot parse query. See the error message from the parser below.`,
	)
	console.error(parsedResult)
	return undefined
	}
	return {
	operationType: parsedResult.operationType,
	operationName: parsedResult.operationName,
	variables,
	}
	}

We can now distinguish between regular REST API requests and those that are GraphQL using the said utility.

[webda2l]

@kettanaito Currently there is an issue to handle advanded graphql queries like:

  const query = `
    query (
      $after: String
      $limit: Int = 10
    ) {
      collectionQueryLessons (
        after: $after
        first: $limit
      ) {
        ..........FIELDS..........
      }
    }
  `

This query is not detected as REST but not right detected as GRAPHQL neither:
[MSW] Failed to intercept a GraphQL request at "POST http://localhost:8008/v3/api/graphql": unnamed GraphQL operations are not supported.
And so, I require to come back to the simpler query:

  const query = `
    query collectionQueryLessons {
        ..........FIELDS..........
    }
  `

Nobody use advanced graphql queries like this? Have you a quick fix in mind? Thanks!

[kettanaito]

The issue above is related to your query being unnamed, which is stated in the error message. MSW doesn't support unnamed queries when using graphql.query/graphql.mutation handlers. You may want to use graphql.operation instead, that captures all GraphQL operations regardless of the query name.

The fact that you see that error message means that the library successfully determined that request as a GreaphQL request. You cannot target such query by name anyway, because it doesn't have it.

consts query = `
  # Now your query is named,
  query MyQuery {
    collectionQueryLessons(...) {}
  }
`

// ...and can be targeted by MSW.
graphql.query('MyQuery', (req, res, ctx) => {...})

The complexity of the query itself has no effect here. We use graphql package to parse a query, so as long as it's a valid query, it will be parsed. If there's a parsing error, you'll see a respective exception.

[webda2l]

Ok I thought that collectionQueryLessons could be parsed as the query name for my first case:

  const query = `
    query (
      $after: String
      $limit: Int = 10
    ) {
      collectionQueryLessons (
        after: $after
        first: $limit
      ) {
        ..........FIELDS..........
      }
    }
  `

but no, it's different. And so:

  const query = `
    query LessonList (
      $after: String
      $limit: Int = 10
    ) {
      collectionQueryLessons (
        after: $after
        first: $limit
      ) {
        ..........FIELDS..........
      }
    }
  `

is working fine! Thanks!

[kettanaito]

collectionQueryLessons is a field, not a query, that's why it doesn't match without your query being explicitly named. A single query may contain multiple fields. MSW intercepts GraphQL operations based on their name, not the fields they have.

[brantleyenglish]

@kettanaito I'm having trouble having a REST api call being mistaken as graphql with msw.

  console.error
    [MSW] Failed to intercept a GraphQL request to "GET https://website.dev/v1/load": cannot parse query. See the error message from the parser below.

    Syntax Error: Expected Name, found String "measures".

The input from:

function parseGraphQLRequest(request) {
    const input = getGraphQLInput(request);
 ...

console logs as:

{
  query: '{"measures":["Reads.uniqueUserCount"],"order":[["Reads.uniqueUserCount","desc"]],"dimensions":["Reads.book"],"limit":5}',
  variables: undefined
}

My server handlers.ts includes graphql queries as well, but I would like for this one to be parsed as rest:

  rest.get('https://website.dev/cubejs-api/v1/load', (req, res, ctx) => {
    return res(ctx.status(200), ctx.json(exampleBooksReadCubeJs));
  }),

Is there anything I am not setting up correctly? Is it possible to mix graphql and rest calls in one handler?
For more context, I am using import { useCubeQuery } from '@cubejs-client/react'; to make the api call on the file I am testing.

  const { resultSet, isLoading, error } = useCubeQuery({
    measures: ['Reads.uniqueUserCount'],
    order: [['Reads.uniqueUserCount', 'desc']],
    dimensions: ['Reads.book'],
    limit: 5,
  });

Using "msw": "0.39.1",
Thanks so much for any help!

[kettanaito]

Hey. I'd be happy to look into this if you open an issue with a reproduction repository. Thanks.

[brantleyenglish]

Thanks so much!
I made an issue here:
#1184

[kettanaito]

I've lined up a proposal to the GraphQL specification to adopt an identifier that'd allow distinguishing intended GraphQL requests from other requests.

To my surprise, the working group behind the spec has already thought this through and has arrived at the very same conclusion that I'm suggesting!

"GraphQL over HTTP" specification now encourages to use Content-Type: application/graphql+json when performing GraphQl requests. This is a fantastic and reliable way for MSW to tell apart GraphQL requests (we can finally ditch a huge guesswork logic around it!).

Read the GraphQL over HTTP spec

I will remain in the discussion loop to see if this change is safe to suggest to GraphQL clients. I'd love to propagate this to Apollo, URQL, you-name-it so everybody has a decent experience.

[mattcosta7]

Since not all clients/servers will implement this

I wonder if we could move to deprecate the base handler for graphql, and force a graphql.link call to generate the handler bound to a specific url, using that to ensure that urls which aren't specifically listened to aren't intercepting incorrect? it seems like that might alleviate some of the issues with rest queries parsing when they wouldn't otherwise need to?

[mattcosta7]

It's most frustrating, i think, when you order handlers to avoid the issue (rest then graphql) but apply a server.use(graphql.query()) in a test, which will start matching rest requests also. hmmm

[shunxing]

Hi there,

Is there currently a way for msw not to catch REST requests when the body contains query ? I'm facing that issue and jumping from one issue to another in the repo but I can't find a proper solution that has been proposed.

#1184

[mattcosta7]

Have a thought for avoiding this in the case where users call graphql.link to define an endpoint first, which might be a good compromise here

#1871

[mattcosta7]

For anyone coming along this discussion:

In version 2.0.9 we shipped #1871 which should help differentiate graphql from rest requests and avoid the console.error discussed here.

That version allows us to bail out of request parsing early if the endpoint is not specifically designated as a graphql endpoing when using graphql.link() and then utilizing the handlers returned from that binding instead of the raw utilities.

To modify existing code:

import {graphql, http} from 'msw'

+ const exampleGraphqlApi = graphql.link("https://example.com/graphql")

const worker = setupWorker(
-  graphql.query('GetUser', ...),
+  exampleGraphqlApi.query('GetUser', ...),
  http.post("https://example.com/users", ({ request }) => {
     const {query} = await request.json()
  })
)

Before, we'd parse requests to https://example.com/users when using the raw graphql.query to see if it was compatible. After 2.0.9 with this change we'll avoid parsing if the endpoint is not defined via that link property.

this should also make it slightly more performant on large numbers of graphql handlers, since they'll parse less frequently

[mattcosta7]

I've also opened #1892 to suggest that we actually force this graphql.link call to bind an endpoint prior to anything else, which should be low effort to transition, but a breaking change.