hotchocolate: A JavaScript repository from keithhenning

Hot Chocolate is a GraphQL server for .NET Core and .NET Classic

Hot Chocolate is a GraphQL server and parser implementation based on the current GraphQL June 2018 specification defined by Facebook.

We are currently in the process of closing some gaps and hope to finalise Version 1 by December. We have listed our progress toward version one at the bottom of this readme.

Getting Started

If you are just getting started with GraphQL a good way to learn is visiting GraphQL.org. We have implemented the Star Wars example with the Hot Chocolate API and you can use our example implementation to follow along.

To generate the example project, head over to your console and fire up the following commands:

mkdir starwars
cd starwars
dotnet new -i HotChocolate.Templates.StarWars
dotnet new starwars

The GraphQL specification and more is available on the Facebook GraphQL repository.

Using Hot Chocolate

The easiest way to get a feel for the API is to walk through our README example. If you need additional information, you can also have a look at our documentation.

Hot Chocolate can build a GraphQL schema, serve queries against that schema and host that schema for web requests.

For our examples we use .net core and the dotnet CLI which you can download here.

Let’s get started by setting up a new console application that we will use to showcase how to set up a GraphQL schema and execute queries against it.

mkdir graphql-demo
cd graphql-demo
dotnet new console -n graphql-console

Now add the query engine package to your project with the following command.

dotnet add package HotChocolate

The GraphQL schema describes the capabilities of a GraphQL API. Hot Chocolate allows you to do that code-first by defining .net classes describing that schema or schema-first by defining the schema in the GraphQL syntax and binding resolvers to it. Our README walkthrough shows you the code-first approach.

The following example shows the code-first approach.

public class Program
{
    public static void Main(string[] args)
    {
        var schema = Schema.Create(c => c.RegisterQueryType<Query>());
    }
}

public class Query
{
    public string Hello() => "world";
}

The code above defines a simple schema with one type Query and one field hello that returns a string.

If you would write that schema down in the GraphQL syntax it would look as follows:

type Query {
  hello: String
}

Moreover, we bound a resolver to the field that returns a fixed value world. A resolver is basically a function that resolves the data for the specified field.

In order to serve up queries against our schema lets make it executable:

var executer = schema.MakeExecutable();

Now that the schema is setup and executable we can serve up a query against it.

{
  hello
}

// Prints
// {
//   data: { hello: "world" }
// }
Console.WriteLine(executer.Execute("{ hello }"));

This runs a query fetching the one field defined. The graphql function will first ensure the query is syntactically and semantically valid before executing it, reporting errors otherwise.

// {
//   "errors": [
//     {
//       "FieldName": "foo",
//       "Locations": [
//         {
//           "Line": 1,
//           "Column": 3
//         }
//       ],
//       "Message": "Could not resolve the specified field."
//     }
//   ]
// }
Console.WriteLine(executer.Execute("{ foo }"));

In order to set up a GraphQL HTTP endpoint, Hot Chocolate comes with an ASP.net core middleware.

Create a new project with the web template that comes with your dotnet CLI.

dotnet new web -n graphql-web

Now add our middleware package to the project with the following command.

dotnet add package HotChocolate.AspNetCore

Open the Startup.cs and add the following code.

protected override void ConfigureServices(IServiceCollection services)
{
    services.AddGraphQL(c => c.RegisterQueryType<ObjectType<Query>>());
}

The above example adds the GraphQL schema and the execution engine to the dependency injection.

protected override void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseGraphQL();
}

This will set up all the necessary endpoints to query the GraphQL schema via HTTP GET or HTTP POST. In order to run a query against your schema, start your web host and get GraphiQL.

By default, the middleware will be configured to listen on the service root for GraphQL requests. If you want to use a different endpoint route you can pass the desired route into the UseGraphQL instruction.

protected override void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseGraphQL("Foo/Bar");
}

We are also currently working on a middleware for ASP.net classic which is planned for Version 0.6.0.

Templates

Apart from the Star Wars template, we also have a GraphQL server template that generates a project with everything hooked up so that you can start building your API quickly.

To install the GraphQL server template, run the following command:

dotnet new -i HotChocolate.Templates.Server

Now that you have implemented this you can generate a new server project by running the following commands.

mkdir myserver
cd myserver
dotnet new graphql-server

Features and Roadmap

We currently support the following parts of the current June 2018 specification of GraphQL.

Types

Scalar Types

Directives

Skip
Continue
Deprecated

Validation

Validation

Execution

Query
Mutation
Subscription

Introspection

Fields
- __typename
- __type
- __schema
__Schema
- types
- queryType
- mutationType
- subscriptionType
- directives
__Type
- kind
- name
- fields
- interfaces
- possibleTypes
- enumValues
- inputFields
- ofType

Moreover, we are working on the following parts that are not defined in the spec.

Draft Features

We are currently working on the following features that are proposed for the next GraphQL specification.

Limit directive uniqueness to explicitly marked directives (#291 in development - 0.7.0)
Add rules for how circular references in Input Objects are handled (in development - 0.10.0)
Add description to Schema (in development - 0.9.0)
"Directive order is significant" section (in development - 0.7.0)

Additional Scalar Types

Additional Directives

Schema Stitching (in development - 0.8.0)
HTTP Directives (in development - 0.8.0)
Custom Schema Directives
Custom Query Directives

Execution Engine

Custom Context Objects
Data Loader Integration / Batched Operations

Schema Creation

Schema-First approach
Code-First approach

Supported Frameworks

GraphQL Compatibility Acceptance Tests

We are now investing to implement the GraphQL Compatibility Acceptance Tests for Hot Chocolate. We should have the first test running with Version 0.8.0 and should have this finished until Version 0.11.0.

More about GraphQL compatibility acceptance tests can be read here.

Documentation

For more examples and detailed documentation, click here.

For documentation about our DataLoader implementation click here.

keithhenning/hotchocolate