Intro to GraphQL

Rye’s eCommerce API is built using GraphQL, a powerful and flexible query language that allows you to request exactly the data you need for your application. GraphQL provides a single endpoint for all your data requirements, making it efficient and easy to work with.

Unlike traditional REST APIs that expose multiple endpoints, each returning a fixed data structure, GraphQL empowers you to construct precise queries to fetch only the necessary data. This eliminates the need for over-fetching or under-fetching data, resulting in optimized performance and reduced bandwidth usage.

Rye’s production GraphQL API endpoint is: https://graphql.api.rye.com/v1/query.

In this guide, we’ll explore the fundamental concepts of GraphQL, including queries, mutations, object types, and the GraphQL playground. Let’s get started!

​

Queries and Mutations

GraphQL operations are categorized into two types: queries and mutations.

​

Queries

Queries are used to fetch data from the server. They allow you to specify the exact fields you want to retrieve for a given object or a set of objects. Queries are read-only operations and do not modify any data.

Here’s an example query that retrieves some data about an Amazon product within the Rye catalog:

query {
  productByID(
    input: {
      id: "B00TTD9BRC"
      marketplace: AMAZON
    }
  ) {
    id
    title
    price {
      currency
      value
    }
    description
  }
}

{
  "data": {
    "productByID": {
      "id": "B00TTD9BRC",
      "title": "CeraVe Moisturizing Cream | Body and Face Moisturizer for Dry Skin | Body Cream with Hyaluronic Acid and Ceramides | Normal | Fragrance Free | 19 Oz | Packages May Vary 19oz Cream",
      "price": {
        "currency": "USD",
        "value": 1778
      },
      "description": ""
    }
  }
}

​

Mutations

Mutations are used to modify data on the server. They allow you to create, update, or delete data. Mutations typically require input arguments to specify the data to be modified.

Here’s an example mutation that creates a new cart containing the product we looked up earlier:

mutation {
  createCart(
    items: {
      amazonCartItemsInput: [{
        quantity: 1
        productId: "B00TTD9BRC"
      }]
    }
  ) {
    cart {
      id
      isShippingRequired
    }
    errors {
      code
      message
    }
  }
}

{
  "data": {
    "createCart": {
      "cart": {
        "id": "OW8RVY2jhFcN3I2qPNrB",
        "isShippingRequired": true
      },
      "errors": []
    }
  }
}

​

Object Types and Fields

In GraphQL, data is represented as a graph of interconnected objects. Each object type defines a set of fields that can be queried or mutated.

For example, the Product object type in Rye’s API may have fields like id, title, price, description, etc.

You can query specific fields of an object by including them in your query. This allows you to retrieve only the data you need, reducing the amount of data transferred over the network.

​

Inline Fragments

In many parts of the Rye API, a single field could be one of several types. The productByID query, for instance, is capable of returning either an AmazonProduct or a ShopifyProduct object depending on the product ID.

Common fields between these types like title or price can be queried directly. Fields specific to a particular type, on the other hand, must be queried using “inline fragment” syntax. Here’s an example of how to retrieve the ShopifyVariant-specific price field:

query GetShopifyProductWithVariantPrices {
  productByID(
    input: {
      id: "6806717890647"
      marketplace: SHOPIFY
    }
  ) {
    id
    title
    variants {
      id
      title
      ... on ShopifyVariant {
        price
      }
    }
  }
}

{
  "data": {
    "productByID": {
      "id": "6806717890647",
      "title": "test digital product",
      "variants": [
        {
          "id": "40182307127383",
          "title": "Medium",
          "price": "$12.23"
        },
        {
          "id": "40182307160151",
          "title": "Small",
          "price": "$15.23"
        }
      ]
    }
  }
}

​

GraphQL Playground

Rye provides a web-based GraphQL playground that allows you to interactively explore and test the API. The playground offers features like syntax highlighting, autocompletion, and real-time error highlighting, making it easier to construct and debug your queries and mutations.

To access the GraphQL playground:

1. Open your web browser and navigate to the Rye Console
2. Navigate to the “GraphQL” tab
3. You will see the GraphQL playground interface where you can enter your queries and mutations.
4. The documentation panel on the right side provides information about the available object types, fields, and operations.

​

Next Steps

Now that you have a basic understanding of GraphQL, start building your app with Rye or explore the API references.