Forem: Lucy

Getting Started with GraphQL

Lucy — Wed, 31 Jul 2024 14:00:00 +0000

Welcome to the world of GraphQL! At its core, GraphQL is both a query language for your API and a server-side runtime for executing those queries. It uses a type system you define for your data. GraphQL isn’t just another tool—it represents a new way of thinking about how data is loaded and managed in applications. If you’re coming from a background in RESTful APIs, you are in for a treat.

Most of us are familiar with companies like Meta (Facebook), who developed GraphQL, or others who have adopted GraphQL to streamline and power their data interactions. Those companies include GitHub, Wayfair, Atlassian, and Intuit.

What makes GraphQL stand out? Ultimately, GraphQL gives you the ability to request exactly the data you need—nothing more and nothing less—and to retrieve that from a single endpoint.

In this guide, we’ll cover the essentials: what GraphQL is, how it differs from REST, and how to start integrating it into your projects. We’ll walk you through this step by step. Let’s begin with the question most asked by API developers who are new to GraphQL.

How Does GraphQL Differ from REST?

When working with APIs, you're probably used to REST, where each resource, like users or products, has its own URL. This setup can lead to a lot of endpoints, and sometimes, fetching simple information requires multiple requests. For instance, imagine you need to generate a summary of an order for a customer. You might need the date the order was placed and the names of the products in that order. With REST, this would typically involve:

Sending a request to the /orders endpoint to get the order dates.
Sending another request to the /products endpoint to fetch the product names.
Possibly sending another request to the /user endpoint to confirm customer details.

In each of these calls, REST might send back much more data than you need—like product prices, descriptions, or user addresses—which you won’t use for your summary.

Selective data retrieval
With GraphQL, you avoid this inefficiency by specifying exactly what you need: just the order date and product names, nothing more. This not only cuts down on the data transferred over the network but also significantly speeds up response times, making applications quicker and more responsive.

Single endpoint approach
Unlike REST, which uses multiple endpoints, GraphQL operates through a single endpoint. This simplifies the workflow because you don’t have to manage multiple URLs; everything happens in one place.

Efficiency and performance
One of the biggest advantages of using GraphQL is its efficiency. Since you can fetch all the required data in a single request, it reduces the number of requests sent to the server. This is particularly beneficial in complex systems or mobile applications where network performance is crucial.

Strongly typed schema
GraphQL uses a strongly typed system where each operation is backed by a schema defined on the server. This schema acts as a contract between the client and the server, ensuring only valid queries are allowed. It helps catch errors early in the development process, improving the quality of your code.

Understanding the Basics of GraphQL
As you start your journey with GraphQL, it’s important to grasp its fundamental concepts. These include the ways you can query data, modify it, and define the structure of data using GraphQL’s type system. Let’s break these down:

Core operations
At its heart, GraphQL is built around three main operations:

Queries: These are used to read or fetch data. Unlike REST, where you might receive more information than you requested, GraphQL queries are designed to return exactly what you specify, no more and no less. This precision not only makes data retrieval more efficient but also easier to predict and handle in your applications.
Mutations: While queries fetch data, mutations change data. Whether you’re adding new data, modifying existing data, or deleting it, mutations are your go-to operations. They are clearly defined in the schema, so you know exactly what kind of data modification is allowed and what isn’t.
Subscriptions: Although we won't delve deeply into subscriptions here, it's useful to know they exist for real-time data updates. Like listening to live updates from a server, subscriptions allow your application to get immediate data as soon as it changes on the server.

Type system
GraphQL’s type system is like a blueprint for your data. Here’s how it works:

Schema definition: This is where you define every type of data that can be queried or mutated through your GraphQL API. It outlines the structure of both input data (what you send) and output data (what you receive).
Strong typing: Every piece of data has a type, like String, Integer, or a custom type like User or Product. This strict typing helps catch errors during development, as GraphQL will only process queries and mutations that fit the schema.
Resolvers: For every field in your schema, there's a function called a resolver that's responsible for fetching the data for that field. This means whenever a query or mutation requests a specific field, the resolver for that field runs to retrieve or update the data.

Understanding these basics sets the foundation for effectively using GraphQL in your projects. You’ll find that with a strong grasp of queries, mutations, and the type system, transitioning from traditional REST approaches becomes much smoother and more intuitive.

Setting Up a GraphQL Environment
In this section, we’ll set up a GraphQL server to handle a dataset involving users, orders, and products. This will give you a practical feel for how GraphQL manages relationships and queries. We'll use Node.js for our server setup, and we’ll take advantage of a package from Apollo Server.

Apollo GraphQL is widely recognized as a leading provider of open-source tools for GraphQL. It offers a range of user-friendly solutions, such as Apollo Server and Apollo Studio, that help developers create and manage their GraphQL applications more efficiently. It has strong community support and straightforward documentation, making it easy for anyone to start working with GraphQL.

Installation and initial configuration
Whether you’re working in an IDE or directly from the command line, getting started with GraphQL simply requires that you have Node.js and npm installed on your machine. The easiest way to do this is through nvm (Node Version Manager), which you can use to install the latest version of Node.js and npm. You can follow these installation instructions for the simple steps to do this.

With Node.js and npm installed, you’re ready to begin working with GraphQL.

Step 1: Project initialization
First, we’ll start by creating our project directory and initializing it:

~$ mkdir project && cd project
~/project$ npm init -y

Step 2: Install dependencies
Next, install Apollo Server and GraphQL:

~/project$ npm install apollo-server graphql

Step 3: Data preparation
Prepare the data model with some dummy data by creating a file called data.json.

~/project$ touch data.json

This file will contain a mock initial data set, which makes it easier to get up and running with GraphQL, as opposed to needing to set up an entire database backend. The data.json file should have the following contents:

{
  "users": [
    { "id": "1", "name": "Alice" },
    { "id": "2", "name": "Bob" }
  ],
  "orders": [
    { "id": "1", "userId": "1", "products": [{"productId": "1", "quantity": 1}, {"productId": "2", "quantity": 2}] },
    { "id": "2", "userId": "2", "products": [{"productId": "3", "quantity": 1}, {"productId": "4", "quantity": 1}] }
  ],
  "products": [
    { "id": "1", "name": "Laptop", "description": "High performance laptop", "price": 1249.99 },
    { "id": "2", "name": "Smartphone", "description": "Latest model smartphone", "price": 575.00 },
    { "id": "3", "name": "Tablet", "description": "Portable and powerful tablet", "price": 410.99 },
    { "id": "4", "name": "Headphones", "description": "Noise cancelling headphones", "price": 199.00 }
  ]
}

Server setup

Step 4: Define GraphQL schema and resolvers
In a server.js file, define our GraphQL schema (with Apollo Server, the convention is to define this in typeDefs), which includes types for User, Order, Product, and their relationships. Also, define the resolvers to specify how the data for each field in your schema is fetched from the data source.

~/project$ touch server.js

The server.js file should look like this:

// server.js
const { ApolloServer, gql } = require('apollo-server');
const data = require('./data.json');

// Type definitions define the "shape" of your data and specify which ways the data can be fetched from the GraphQL server.
const typeDefs = gql`
  type User {
    id: ID
    name: String
    orders: [Order]
  }
  type Order {
    id: ID
    userId: ID
    products: [OrderProduct]
  }
  type OrderProduct {
    productId: ID
    quantity: Int
    product: Product
  }
  type Product {
    id: ID
    name: String
    description: String
    price: Float
  }
`;

// Resolvers define the technique for fetching the types defined in the schema.
const resolvers = {
  User: {
    orders: (user) => data.orders.filter(
        order => order.userId === user.id
    ),
  },
  OrderProduct: {
    product: (orderProduct) => data.products.find(
        product => product.id === orderProduct.productId
    ),
  }
};

We’ve defined two resolvers above. Notice how in our typeDefs that a User has an array of Orders, and an Order has an array of OrderProducts. In our resolvers, we make it clear that a user’s orders are, naturally, those where the userId matches the user’s id. A similar approach applies to an Order and its OrderProducts. We use resolvers to help define the relationship between data models.

Step 5: Initialize and launch Apollo Server
Next, we initialize Apollo Server with the schema and resolvers, and then we start it up to listen for requests. Add the following to the bottom of server.js:

const server = new ApolloServer({ typeDefs, resolvers });
server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`);
});

This setup gives us a fully functional GraphQL server using Apollo. Next, we’ll dive into how to construct and execute queries to interact with this server setup.

Working with Queries
With our Apollo Server up and running, we can build out the typeDefs and resolvers to handle basic queries.

Define Query in typeDefs

Let’s add a Query type to our typeDefs.

const typeDefs = gql`
  type Query {
    users: [User]
    user(id: ID!): User
    orders: [Order]
    order(id: ID!): Order
    products: [Product]
    product(id: ID!): Product
  }
  type User {...}
  type Order {...}
  …

These definitions establish the type of data that will be returned for each given query. For example, the users query will return an array of Users, while the user query—which will take a single id—will return a single User. Of course, it would make sense that the single User returned is the one with the matching id. However, we use resolvers to make that explicit.

Add Query to resolvers

Let’s update our resolvers object to look like this:

const resolvers = {
  Query: {
    users: () => data.users,
    user: (_, { id }) => data.users.find(user => user.id === id),
    orders: () => data.orders,
    order: (_, { id }) => data.orders.find(order => order.id === id),
    products: () => data.products,
    product: (_, { id }) => data.products.find(product => product.id === id),
  },
  User: { … },
  OrderProduct: { … }
};

We see from how we define each Query in our resolvers that the users query will map to our data.users array. Meanwhile, a specific product query will search the data.products array for the product with the matching id.

Start server
Now, we’re ready to start our server. In the terminal, we execute the following command:

~/project$ node server.js
🚀 Server ready at http://localhost:4000/

Test basic queries

To interact with our GraphQL API from the command line, we can use curl to send HTTP requests to the /graphql endpoint. If you were to visit http://localhost:4000 directly in your browser, you would see the Apollo Studio web interface (more on that below).

Let's say we want to fetch the name and orders for the user with id 1. The GraphQL query in JSON format would look like this:

~$ curl \
   -X POST \
   -H "Content-Type: application/json" \
   -d '{"query": "{ users { id name } }"}' \
   http://localhost:4000/graphql

{"data":{"users":[{"id":"1","name":"Alice"},{"id":"2","name":"Bob"}]}}

In the above request, we are sending a users query, which we defined in our resolvers to be “all the users in the data.users array.” Based on the User schema defined in typeDefs, we can ask for an id, name, and orders for each User. However, in GraphQL, we get to decide how much information we want to receive. In the case of this request, we only want the id and name for each User.

Let’s send another request. This time, we will retrieve all the orders for a specific User, and for each Order, we also want to fetch certain information about the associated OrderProducts.

~$ curl \
   -X POST \
   -H "Content-Type: application/json" \
   -d '{"query": "{ user(id:1) { orders { id products { quantity product { name price } } } } }"}' \
   http://localhost:4000/graphql | json_pp

{
   "data" : {
      "user" : {
         "orders" : [
            {
               "id" : "1",
               "products" : [
                  {
                     "product" : {
                        "name" : "Laptop",
                        "price" : 1249.99
                     },
                     "quantity" : 1
                  },
                  {
                     "product" : {
                        "name" : "Smartphone",
                        "price" : 575
                     },
                     "quantity" : 2
                  }
               ]
            }
         ]
      }
   }
}

Notice that both of our requests were POST requests to the same /graphql endpoint. All our requests will be POST requests, and they’ll all go to this endpoint. Our data payload notes that we are sending a query, and then we specify our query parameters as a JSON string.

Mutations and Updating Data

Mutations are essential for performing write operations in GraphQL. Unlike queries, which are used to fetch data, mutations change data—anything from creating and updating to deleting records. Let’s define some common mutations for your GraphQL API and show how to implement them.

Define Mutation in TypeDefs
First, we’ll extend our GraphQL schema to include mutation type definitions:

const typeDefs = gql`
  type Query { … }
  type Mutation {
    addUser(name: String!): User
    updateUser(id: ID!, name: String!): User
    addProduct(name: String!, description: String, price: Float!): Product
    addOrder(userId: ID!, products: [ProductInput!]!): Order
  }
  input ProductInput {
    productId: ID!
    quantity: Int!
  }
  type User { … }
  type Order { … }
  }

We’re adding four mutations here:

addUser will add a new user with the given string name.
updateUser will update the name of the user with a given id.
addProduct will add a new product with the given name, description, and price.
addOrder will add a new order for a user with the given id, but it will also need to take an array of ProductInput objects, which we also define as a combination of a productId and quantity.

Add Mutation to resolvers
Next, we define resolvers for our mutations.

const resolvers = {
  Query: { ... },
  Mutation: {
    addUser: (_, { name }) => {
      const newUser = { id: String(data.users.length + 1), name };
      data.users.push(newUser);
      return newUser;
    },
    updateUser: (_, { id, name }) => {
      const user = data.users.find(user => user.id === id);
      if (!user) return null;
      user.name = name;
      return user;
    },
    addOrder: (_, { userId, products }) => {
      const newOrder = {
        id: String(data.orders.length + 1),
        userId,
        products
      };
      data.orders.push(newOrder);
      return newOrder;
    },
    addProduct: (_, { name, description, price }) => {
      const newProduct = { id: String(data.products.length + 1), name, description, price };
      data.products.push(newProduct);
      return newProduct;
    }
  },
  User: { ... },
  OrderProduct: { ... }
};

In our resolvers, we specify how the Apollo Server should handle each of our mutation operations. This typically means creating a new object (or finding the object to be updated, in case of updateUser) and then updating data with that object.

Restart server
With our mutations defined, let’s restart our server with node server.js again.

Test mutation operations in Apollo Studio
Apollo has a convenient and feature-rich web interface called Apollo Explorer that can connect to our development environment server to make querying and testing easier. With our server started, we can visit the server URL (if you are running locally, then it will be http://localhost:4000) in our browser, and this will redirect us to Apollo Explorer. Alternatively, visit https://studio.apollographql.com/sandbox/explorer directly.

Let’s test out a few mutation operations in Apollo Explorer. For example, the following operation calls the addUser mutation to add a new user with the name Charlie, and then it returns the resulting id and name of the newly added user.

In Apollo Explorer, the operation looks like this:

What if we wanted to add a new order for Charlie? It would look like this:

Finally, here’s how we might perform an updateUser mutation:

Notice that mutation operations can be followed up with querying for more efficient operations.

A note on handling data
So far, our examples have used an in-memory object called data which started as data read in from a JSON file. This approach is great for learning and quick prototyping, but it isn’t suitable for production environments where data persistence is crucial.

In a production setting, you would typically connect your GraphQL server to a persistent database. The resolvers we've written, which currently manipulate the in-memory data object, would be adjusted to execute queries against this database instead.

Error Handling and Debugging
Handling errors and debugging in GraphQL may differ slightly from how you would do it with traditional REST APIs. Here are some tips for approaching error handling and debugging efficiently:

Check for errors: GraphQL operations typically return a list of errors in the response body. These might not be HTTP status errors but are instead part of the GraphQL response under the errors field. Therefore, you should always check for errors in the response alongside the data to ensure comprehensive error handling.
Logging: Implement logging on the server side to capture requests and errors. This can help you trace issues back to specific queries or mutations.
Validate queries: Use tools like Apollo Explorer during development to validate queries and mutations for syntax and structure before deployment.
Use clear error messages: Design your resolvers to throw errors which include clear and descriptive error messages. This helps clients understand what went wrong without the need to dig into server-side logs.

Tools and Ecosystem

When working with GraphQL—especially as you’re just starting out—you don’t need to build everything from scratch. Take advantage of the rich ecosystem of tools designed to enhance your development experience. Apollo Studio featuring Explorer is a prime example, allowing you to build and test your queries interactively within a web interface. This makes it easier to visualize and manipulate your GraphQL operations.

For an alternative in-browser GraphQL IDEs, there is also GraphiQL. For API testing and query building, Postman—traditionally known for handling REST APIs—also supports GraphQL. Additionally, GraphQL Voyager is a tool for visually exploring your GraphQL API as an interactive graph. This can be particularly useful for understanding and documenting the relationships between entities.

Conclusion

Congratulations on navigating through the fundamentals of GraphQL! By now, you should have a solid understanding of how GraphQL differs from traditional REST APIs, its efficiency in fetching and manipulating data, and the flexibility it offers through queries and mutations.

Throughout this guide, we've explored:

Setting up a GraphQL environment using Apollo Server.
Constructing and executing queries to retrieve data, demonstrating the efficiency of GraphQL in fetching exactly only the data that you need.
Implementing mutations to modify data.
Tips for error handling and debugging.
Additional tools that can help you in your GraphQL learning journey.

Continue exploring GraphQL, and spend time looking into advanced features like subscriptions. As you design APIs for projects in the future, consider whether the efficiency and power of GraphQL may be a better fit for your needs than a traditional REST API. Keep learning, keep building, and make the most of what GraphQL has to offer!

Open Source for Beginners: FAQ Guide

Lucy — Fri, 15 Mar 2024 21:18:09 +0000

Interested in contributing to open source, but not sure where to start? As a developer advocate working on Intuit Open Source, I hear this quite a lot from our community. To help you get over that cold start problem, we've compiled a beginner-friendly FAQ to jumpstart your first open source contribution.

If you prefer video, consider checking out our OSS beginners video guide as well!

Where can I find good active projects to contribute to?

firsttimersonly.com has a listing of various first-timer resources
GitHub issues search: #good-first-issue
awesome-for-beginners (categorized by language)
Nontechnical contribution resources: awesome-for-non-programmers

Our #1 tip: just do it! Don't get too stuck looking for the ideal first project, just choose something you can do and start getting your feet wet.

How do I feature OSS work on my resume or portfolio?
You can list open source contributions under the "Projects" or "Volunteering" headers on your resume. Rather than listing every contribution you've ever made, focus on the projects you're most associated with, and highlight the number of contributions you made to each of those projects.

Even if it's just one pull request, it's worth showing off your work to potential employers. An open source PR demonstrates that you're able to get up to speed with an unknown codebase quickly, a valuable skill for any technical role in the industry.

What technologies do I need to know to contribute to open source?
A working understanding of Git and GitHub is essential, but beyond that, the specific technology stack and tools you'll need will depend on the project you want to contribute to. If you're looking to deepen your expertise in a particular skill set, take a closer look at the open source libraries out there leveraging the tools or languages you’re hoping to learn, and find one that fits your learning goals.

E.g. As a frontend developer looking to improve my TypeScript fluency, I could search GitHub for good first issues tagged on projects that use TypeScript.

What happens when multiple people want to work on the same issue?
Most maintainers will typically have a "first come, first serve" policy when it comes to assigning issues to contributors. If you see an issue you'd like to tackle, make sure it's up for grabs before starting work by commenting on the issue and getting a confirmation from a maintainer on the project. It’s also common that someone may claim an issue and then not make progress on it for a while, at which point you’re welcome to step in and take over (with the maintainers’ blessing, of course).

When should I stop taking good first issues?
The beauty of open source is that there's always something new to learn and contribute to. Take good first issues as long as you feel like you need to, but don't be afraid to move on when you outgrow them.

How can I generate interest in a new open source project?
Building a strong community around your project is key to its success. Offer good first issues, participate in events and open source conferences, create clean documentation and video guides, and don't hesitate to ask for feedback from others in the field. Remember that it takes time and consistency to build community momentum, and there are entire teams and OSPOs dedicated to this specific problem, so don’t be too hard on yourself if things don’t take off immediately or if you can’t achieve the perfectly consistent cadence. Little by little, you’ll get there!

What other resources can you recommend for beginners?

Here's a good Git workflow walkthrough, or you can step through the first-contributions guide
Conventional commits

Let us know in the comments if you have any other questions, and we’ll answer as much as we can. If you’re still looking around for a project, our Intuit Open Source projects can also be a great place to start.

Happy coding, open-sourcerors!

Hacktoberfest 2023 @ Intuit: Maintainer Spotlight

Lucy — Wed, 25 Oct 2023 17:15:30 +0000

As Hacktoberfest 2023 comes to an end, we at Intuit are excited to send rewards to our internal and external contributors for their amazing contributions. But before we do, we want to take a moment to recognize our maintainers!

Intuit has been participating in Hacktoberfest since 2019 by offering special incentives to employees for contributing to open source projects, and this year we took it to the next level by sending rewards (cool t-shirts!) to outside contributors to Intuit libraries as well. It’s important to remember that these contributions are only possible thanks to the hard work of our maintainer teams reviewing pull requests and keeping issues up to date.

We wish we could highlight every single one of our 130+ open source projects here, but here’s a short list of featured maintainer teams and their projects:

Graph Quilt

graph-quilt is an open source Java library that provides recursive schema stitching and Apollo Federation style schema composition for GraphQL APIs. The project includes a modular set of libraries with features including a Representational State Transfer (REST) adapter, GraphQL authorization, and a reference implementation of a graph-quilt gateway. There are even more features coming soon, so keep an eye out for updates!

Maintainers Ashpak Shaikh, Carlo Aureus, and Kyle Moore released a video demo and walkthrough on the Intuit Developers YouTube channel. Check it out here:

Ashpak also recently spoke in-depth about graph-quilt at GraphQLConf 2023. See the recording of his talk here!

Numaproj

numaproj is a collection of Kubernetes-native tools for doing real-time operation data analytics. Currently it includes numaflow, a massively parallel, real-time data and stream processing engine, and numalogic, ML models and tools for real-time operational data analytics.

Maintainers Derek Wang and Vigith Maurice recently gave a talk at All Things Open walking through how to build a large scale AIOps platform with open source technologies, including numaproj tools. The recording of their talk will be live soon on the All Things Open YouTube channel, so stay tuned! Maintainer Sri Harsha Yayi also joined Derek for a presentation at the Hacktoberfest Happy Hour we hosted at Intuit’s Mountain View and San Diego campuses.

numaproj is still a young and growing project, and if you’d like to follow along on the journey, consider joining the team on Slack, or follow the numaproj blog.

Player

Player is a framework for building cross-platform dynamic experiences. The core engine is authored in TypeScript with specific adaptors to natively render on iOS, Android, and React. Start by supplying some semantic JSON content, where you can describe views, your data, validation rules, and much more. Add your own asset library to handle the rendering, and voilà, you have a full dynamic user experience.

Player’s maintainer team is one of our most active here at Intuit, and they’ve been an incredible source of open source energy, year-round. To see the library in action, check out our YouTube video featuring maintainer Adam Dierkens here:

Cello

Cello is an engine for Cloud deployments: infrastructure as code (IaC) with GitOps, with isolation from your Cloud provider, all Cloud-agnostic. It fits into any CI/CD system — Jenkins, GitHub actions, you name it. We developed Cello to help us manage our complex set of various IaCs.

Maintainer Jerome Kuptz recently gave a lightning talk demonstrating Cello’s features for a round of Hacktoberfest lightning talks we did internally at Intuit. We’ll work on getting that talk shared soon on the Intuit Developers YouTube channel, but please check out Cello’s Quick Start guide in the meantime!

Trapheus (and TrapheusAI)

Trapheus is a tool for restoring relational database service (RDS) instances in AWS without worrying about client downtime or configuration retention. It supports individual RDS snapshot as well as cluster snapshot restore operations. Modeled as a state machine, with the help of AWS step functions, Trapheus restores the RDS instance in a much faster way than the usual SQL dump preserving the same instance endpoint and configurations as before.

Maintainer Rohit Kumar recently published a blog post on Intuit’s Engineering Blog celebrating 3 years since Trapheus’ first release during Hacktoberfest 2020, and announcing the launch of TrapheusAI, a next-generation data search and analysis assistant that can overcome the challenges of traditional keyword search with powerful data analyses using natural language. See the demo here:

argoproj

How could we do an Intuit open source software maintainer feature without Argo? Argo Project is one of our largest open source projects, with a vibrant contributor, maintainer, and user community. Argo is a collection of open source tools for Kubernetes to run workflows, manage clusters, and do GitOps right. The project includes argo-workflows, argo-rollouts, argo-cd, and more.

Maintainer Michael Crenshaw gave a talk on Argo CD for the Hacktoberfest lightning talks mentioned earlier, which we’ll work on publishing soon. The Argo community is also hosting an in-person Kubernetes meetup at the Intuit Mountain View campus.

—

This was only a tiny fraction of all the open source projects we’re proud to work on here at Intuit. Hacktoberfest may be drawing to a close, but the open source work continues through the rest of the year. Whether you managed to get a contribution done this October or not, we hope to see you out there in the open source community.

A huge, endless thank you to all of our maintainers and contributors for your hard work and dedication to the open source community. There are still a few days left in October, so keep those contributions coming (see Intuit’s Hacktoberfest incentives here), and Happy Hacktoberfest!