- read

How to Build a GraphQL API using GraphQL-Go Part 1

Golang
Trending
#Go

Victor Kabata 8

Introduction

GraphQL is a query language and server-side runtime for APIs that prioritizes giving clients precisely the data they request and no more.

In practice, graphQL allows front-end developers to send queries asking for the data they need from the server.

Advantages of GraphQL

  • GraphQL mitigates the problem of over-fetching (client downloading more data than it requires) and under-fetching (client doesn’t get all the info it needs from one endpoint so it will need to make other network calls to different endpoints to get the entire info.
  • GraphQL schema offers a single truth source, resulting in an easy federation of the entire API.
  • GraphQL lets the APIs evolve without breaking the queries and lets the client request data types hence suitable for developing stable APIs

Disadvantages of GraphQL

  • To make the most out of GraphQL, one has to have familiarity with REST APIs.
  • GraphQL shifts most of the work of a data query on the server side, making things a bit complicated for the server.

Terminologies

  • Schema describes all the possible data that clients can query through that service
  • Fields are attributes associated with a piece of data.
  • Queries are GraphQL operations that return only the data you specify. Similar to GET operations in REST API.
  • Mutations are graphQL operations that alter data on the server. Similar to POST/PATCH/DELETE in REST API.

Let’s get started …

For this project, we’ll be creating a simple GraphQL API that retrieves, creates, updates and deletes notes from a data source.

In order to keep this tutorial really simple, we’ll not use a database as our data source. We will use a simple golang struct to mock database functionality. However, this can later be interchanged easily with the real database implementation

  1. Create a golang project folder inside your GOPATH directory and run the following go command the initialize the golang module:
go mod init project-name

2. Install graphql-go and graphql-go-handler packages

3. Create the main.go file which will serve as the application’s entry point. In the main.go file, create the main function where we’ll place all the code needed to create our graphQL API. For now, we’ll just print a string as output and run the application

4. Now that we have the main function setup and can run the basic application, let’s set up the model of the data we’ll be working with and a mock database with values.

5. Next we’ll define a new graphQL type of note model using graphql.NewObject inside the main function. Then we define the name, description and fields(we also define field name and data type) of the note type inside graphQL.ObjectConfig

6. Next we’ll define a field/query operation that returns a list of all notes from our data source. We define the name of the query, the data type of the output and most importantly a resolver which returns the data we need

For this case, we’ll be returning a list of all notes in the data source so we’ll just return the slice of notes we created in step 4. For simplicity, we will not return the error value.

7. We then create the rootQuery which will serve as the main graphql entry point. We define the name of the root query and specify its fields(fields created in step 6)

8. We are halfway there but we need to finish setting up the API’s schema config and its schema

9. We’ll then create a handler that will handle the requests to the server and set up the API endpoint

10. Last but not least, we’ll set up the HTTP server for our graphQL API

…and we are done setting up a simple GraphQL API that retrieves the fields of note model from the data source. We can test our API from Postman.

From Postman we’ll use http://localhost:8080/graphql to query the graphQL server. We can then request any of the fields(id, title, description or created_at) that we need to be returned to the client from the server

Bonus

Apollo has a graphql sandbox IDE that makes testing your graphQL server in the local environment easy using the graphQL sandbox.

In this last part, we’ll set up a graphQL sandbox that will allow us to test the graphQL endpoint easily without requiring the Postman client.

Next start the graphQL server, open your web browser and input: http://localhost:8080/sandbox.