Documentation on adding custom directives

[JakeAngell]

I'm looking to create a custom directive for my GraphQL server. I want my server to omit certain fields conditionally, based on the value of the fields that are decorated with the directive.

For example:

{
  allSites {
    siteId @overN(n:4)
    siteName
  }
}

Would return all sites and their names, but only include their siteId if its value is over 4.

Is there any documentation or an API I could read so I can see the best practice when adding a new directive?

[leebyron]

There isn't documentation outside the codebase itself at present, but you can take a look at directives.js which exports the GraphQLDirective class constructor and schema.js which exports the GraphQLSchema class constructor - one of the properties of the object given to that constructor is directives, which is an array of directives to use.

The difficulty you may run into is introducing non-spec-compliant behavior into the executor itself to omit fields. You'll likely need to fork this library to make the necessary changes.

[JakeAngell]

Thanks for the response!

So using a directive for this purpose would violate the spec? Why would that be? I just see it as the same as the @include directive with the conditional fulfilled server side. Not sure why doing this could cause issues.

[leebyron]

Violate is a strong word for what this directive would propose - rather it's just adding new execution behavior that's not defined by the spec. That means adding this directive won't make your service any less GraphQL, it would be GraphQL plus more behavior. Violation implies a breaking change that makes a service not-quite-GraphQL instead. I know that's kind of word pickiness, but it's a subtle but important point in this case. Just trying to say that you're not doing anything wrong by doing this, but that there also are not hooks into the executor in this library that allow for easy addition of behavioral changes like this so it might not be very straight-forward.

[JakeAngell]

I see, that makes perfect sense.

Thanks again for the detailed and thorough reply.