Run your first server

By the end of this page you will have a Go GraphQL server running on http://localhost:4000.

You will define a schema with Go types, build a grx server, run it with net/http, and send one query. Framework integrations come after this page.

What you will buildCopy Anchor Link

The request flow is:

1. net/http receives the request.
2. The grx handler selects the HTTP transport.
3. grx parses and validates the GraphQL document.
4. The executor calls the Query resolver.
5. grx writes a JSON response.

This is the default path for queries and mutations. Subscriptions add a WebSocket or SSE transport later.

1. Create the moduleCopy Anchor Link

mkdir hello-grx
cd hello-grx
go mod init example.com/hello-grx
go get github.com/grx-gql/grx@latest
mkdir graph

2. Define the schemaCopy Anchor Link

Create graph/schema.go:

package graph

import (
	"context"

	"github.com/grx-gql/grx/schema"
)

type User struct {
	ID   string `gql:"id,nonNull"`
	Name string `gql:"name,nonNull"`
}

type UserArgs struct {
	ID string `gql:"id,nonNull"`
}

type Query struct{}

func (Query) User(ctx context.Context, args UserArgs) (*User, error) {
	return &User{ID: args.ID, Name: "Ada Lovelace"}, nil
}

func Schema() schema.Config {
	return schema.Config{Query: Query{}}
}

Query is the required root. Its exported methods become top-level query fields. The User method becomes the GraphQL field user.

The gql tags make the public contract explicit. Here they mark id and name as non-null and define the argument name as id.

Read Define your schema for objects, inputs, lists, custom scalars, and root composition.

3. Build the serverCopy Anchor Link

Create main.go:

package main

import (
	"log"
	"net/http"

	"example.com/hello-grx/graph"
	"github.com/grx-gql/grx"
)

func main() {
	server, err := grx.NewServer(
		grx.WithSchema(graph.Schema()),
		grx.WithPlaygroundPath("/"),
	)
	if err != nil {
		log.Fatal(err)
	}

	log.Println("GraphiQL: http://localhost:4000/")
	log.Println("GraphQL: POST http://localhost:4000/graphql")
	log.Fatal(http.ListenAndServe(":4000", server))
}

Run it:

go run .

Open http://localhost:4000/ and run:

{
  user(id: "user_1") {
    id
    name
  }
}

What grx ownsCopy Anchor Link

grx builds and executes the GraphQL schema and provides the GraphQL transports. Your application still owns routing, CORS, authentication middleware, TLS, databases, and deployment.

Read Runtime boundaries before adding those concerns to a production service.

Next stepsCopy Anchor Link

• Why choose grx
• Define your schema
• Choose an HTTP integration
• Transports
• Authentication and authorization
• Deployment and scaling