Odyssey

Intro to GraphQL with .NET (C#) & Hot Chocolate
beta

Overview and setupWhat is GraphQL?Hot ChocolateHello worldApollo Sandbox ExplorerBuilding a schemaThe Query entry pointREST as a data sourceResolvers & data sourcesGraphQL argumentsA playlist's tracksResolver chainsMutation responseMutation input
1. Overview and setup
2m

Welcome to the start of your GraphQL journey!

What is GraphQL? GraphQL is the developer-friendly query language for the modern web. It transforms how apps fetch data from an API, enabling you to get exactly what you need with a single query.

With a strongly typed schema at its core, GraphQL helps you define relationships between data across any number of systems, empowering you to focus on what your data can do instead of where it's stored.

Throughout this course, we're going to learn how GraphQL fits into our existing architecture and how it works with existing REST APIs and other data sources.

Want a faster way to get started with GraphQL using existing REST APIs? Apollo Connectors make it easier than ever! No servers, no complex resolvers; everything happens in the schema.

We'll learn how to use queries, mutations, arguments, the schema, and resolvers in our GraphQL API.

A diagram showing GraphQL as the contact point between multiple clients and the complex architecture of a modern backend

We'll build a GraphQL server using Hot Chocolate. No, not the warm, chocolatey drink! We're talking about a GraphQL server framework for .NET developers.

Get ready to roll up your sleeves, write some code, test your understanding, and build something cool!

In this lesson, we will:

  • Learn about what we're building
  • Set up our project environment

Pre-requisites

This course uses C# and .NET 8. You should be familiar with C# basic programming concepts to follow along with this course.

We also recommend being familiar with the basics of how to use REST APIs and HTTP requests.

What we're building

Listen up! Ready to tune into what we're building in this course? Drumroll please 🥁

If you couldn't tell from all those music-related cues, we're building a music catalog API called MusicMatcher that helps us find the right soundtrack for the right moment.

Mockup of MusicMatcher

For this first iteration of MusicMatcher, we'll focus on playlists: showcasing featured playlists, listing a playlist's tracks, and adding tracks. In future courses, we'll add more features like pagination, authentication, intermediate schema design concepts, and federation.

Project setup

To follow along with the course, you will need the following:

Code editor or IDE

We'll be using VS Code but you can feel free to use your favorite editor or IDE for .NET development!

If you're using VS Code, we recommend installing a couple of helpful extensions:

  1. The C# Dev Kit extension. We'll be using the Solution Explorer to navigate our project and create new classes. It also helps with code navigation like jumping to class and function definitions, as well as IntelliSense for automatic code completion.

  2. The CSharpier extension. CSharpier is an opinionated code formatter. We recommend configuring it to format your file after every save.

Clone the repo locally

The project repo is the result of running dotnet new web -o Odyssey.MusicMatcher to create a new project based on the ASP.NET Core Empty web template. It also contains some extra instructions in the README on how to get up and running.

git clone https://github.com/apollographql-education/odyssey-intro-hotchocolate

Here's what the project looks like:

📦 Odyssey.MusicMatcher
┣ 📂 Data
┃ ┣ 📄 swagger.json
┣ 📂 Properties
┃ ┣ 📄 launchSettings.json
┃ 📄 appsettings.Development.json
┃ 📄 appsettings.json
┃ 📄 Odyssey.MusicMatcher.csproj
┃ 📄 Odyssey.MusicMatcher.sln
┃ 📄 Program.cs
┗ 📄 README.md

To install dependencies, run:

dotnet build

Don't have .NET installed? Find your download link here. We're using .NET 8 for this course.

Then, check that the project can run successfully:

dotnet run

You should see:

Odyssey.MusicMatcher ❯ dotnet run
Building...
info: Microsoft.Hosting.Lifetime[14]
Now listening on: http://localhost:5059
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
Content root path: /Users/your-path/Odyssey.MusicMatcher

The project will be running on http://localhost:5059 by default!

Task!

Key takeaways

  • GraphQL enables precise data retrieval with a single query, eliminating the need to navigate multiple REST endpoints on the client app side.
  • Hot Chocolate is a GraphQL server framework for .NET developers.

Up next

Let's dive into all things GraphQL. In the next lesson, we'll get into the details of how GraphQL fits into our existing architecture and what exactly makes up a GraphQL server.

Next

Share your questions and comments about this lesson

This course is currently in

beta
. Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.

              GraphQL

              An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

              GraphQL

              An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

              GraphQL

              An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

              mutations

              A GraphQL operation that modifies data on the server. It allows clients to perform create, update, or delete operations, altering the underlying data.

              arguments

              A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

              Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

              query GetHuman {
                human(id: "200") {
                  name
                  height(unit: "meters")
                }
              }
              resolvers

              A function that populates data for a particular field in a GraphQL schema. For example:

              const resolvers = {
                Query: {
                  author(root, args, context, info) {
                    return find(authors, { id: args.id });
                  },
                },
              };
              GraphQL

              An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

              GraphQL server

              A server that contains a GraphQL schema and can resolve client-requested operations that are executed against that schema.

              extensions

              An optional part of a GraphQL response that provides additional metadata that can aid in communication between the server and client and enhance the response handling process. See an example below.

              {
                "data": {
                  "user": {
                    "id": "123",
                    "name": "John Doe",
                    "email": "john.doe@example.com"
                  }
                },
                "extensions": {
                  "metadata": {
                    "requestId": "abc123",
                    "timestamp": "2023-01-01T12:00:00Z"
                  }
                }
              }
              GraphQL

              An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

              query

              A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

              GraphQL server

              A server that contains a GraphQL schema and can resolve client-requested operations that are executed against that schema.

              GraphQL

              An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

              GraphQL server

              A server that contains a GraphQL schema and can resolve client-requested operations that are executed against that schema.

              NEW COURSE ALERT

              Introducing Apollo Connectors

              Connectors are the new and easy way to get started with GraphQL, using existing REST APIs.

              Say goodbye to GraphQL servers and resolvers—now, everything happens in the schema!

              Take the course