GraphQL Endpoint Language

[jimkyndemeyer]

The endpoint language is a variation on the schema shorthand from Facebook.

The purpose of the endpoint language is to declaratively express how a schema is implemented. This includes:

• Field resolution based on meta-data annotations such as @datafetcher.
• Splitting a large schema into multiple files
• Endpoint code-generation for both server and client

The main syntactic differences from the shorthand are as follows:

• Import declarations which allows the schema implementation to be spread across multiple files
• "Auto implementation" of fields in a type that should implement one or more interfaces
• Meta-data on fields is placed before the field, similar to Java annotations, e.g.

Code example:

# file: main.graphqle

# import the Bar interface:
import "bar-schema-fragment"

type Foo implements Bar {
  @DataFetcher("fooAwesomeFieldDataFetcher")
  awesomeField: String
  # fields from Bar are auto-implemented, but can be declared again to add annotations
}

This issue tracks basic language support:

• .graphqle file type
• Parser
• Lexer
• Syntax highlighting
• Formatter
• Folding
• Completion

[sergehuber]

This sounds fantastic can't wait for it to be released. Is there any official specification for this endpoint language ? I couldn't find anything using Google.

[jimkyndemeyer]

@sergehuber This issue and JSGraphQLEndpointParser.bnf is the only official specification at this time. You won't find any info elsewhere since the language design is done by my colleagues and myself.

We're currently using the Endpoint language to build a product, and once we're happy with the language features, the plan is to include the language in the published plugin version.

For now, I'd recommend that you write your schema in a ".graphqls" file (right click -> New -> GraphQL Schema file). Depending on which stack you're using on the server side, the Apollo team has a great set of tools that help you create a working endpoint based on your .graphqls schema file. See their medium post.

/Jim.

[jimkyndemeyer]

Merged to master.

[vepanimas]

@jimkyndemeyer hi! What do you think about supporting this functionality now? It looks like it hasn't become a standard and doesn't have a specification, but it still complicates the code and requires support. Is it used by anyone? Maybe it makes sense to delete this code in the next released version, what do you think? If someone needs it, they can use one of the previous versions.

[jimkyndemeyer]

Hi @vepanimas

The GraphQL Endpoint language is actively used by teams at Elsevier, and as part of my work there I have time to support it as needed.

I could potentially see us migrating to use GraphQL SDL, but we'd have to be able to augment the completion of directive argument values and their reference resolution to get the same level of tooling. I recall having seen ways for plugins to provide extension points for other plugins?

In any case, there's a number of ways to approach cleaning this up for easier overall maintenance of the plugin. For now, is there any specific part of the code that you think needs attention due to the presence of the Endpoint language?

[vepanimas]

@jimkyndemeyer ok, that's all I wanted to know. I mistakenly thought it was outdated, but if it isn't, there are many ways to slightly restructure it with extension points and isolate all the related code in a separate module.

A lot of features inside the WebStorm are done in a similar way. Usually, there is a base class with common functionality that accesses the extension point and polls some providers. For example, this is done with d.ts files, third-party plugins can provide their own definitions so that they are taken into account in the autocomplete and other features.

I think that this could be done later and incrementally, this does not prevent further development in any way.