GraphQL basics

GraphQL is a query language that lets you request exactly the data you need from the Product Hunt API. Learn the basics of writing GraphQL queries.

What is GraphQL

GraphQL is a query language for APIs that lets you specify exactly which fields you want to retrieve. Unlike REST APIs that return fixed data structures, GraphQL lets you shape your response to match your needs.

With GraphQL, you write a query describing the data you want, send it to the API, and get back only that data. This reduces over-fetching (getting data you don't need) and under-fetching (needing to make multiple requests).

Basic query structure

A GraphQL query has a simple structure:

{
  products(first: 10) {
    edges {
      node {
        id
        name
        tagline
      }
    }
  }
}

This query asks for the first 10 products and retrieves their id, name, and tagline. The response will contain only those fields.

Making your first request

To make a GraphQL request to the Product Hunt API, send a POST request to the GraphQL endpoint with your query:

curl https://api.producthunt.com/v2/api/graphql \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ products(first: 5) { edges { node { name tagline } } } }"
  }'

The API will respond with JSON containing your requested data:

{
  "data": {
    "products": {
      "edges": [
        {
          "node": {
            "name": "Product Name",
            "tagline": "Product description"
          }
        }
      ]
    }
  }
}

Queries and fields

A GraphQL query is a request for data. You specify which fields you want, and the API returns only those fields. This is different from REST APIs where endpoints return fixed data structures.

For example, this query retrieves a product's name and description:

{
  product(id: "123") {
    name
    description
  }
}

And this query retrieves additional fields:

{
  product(id: "123") {
    name
    description
    website
    tagline
  }
}

Arguments and filtering

Many GraphQL fields accept arguments that let you filter or customize the results. For example, the products field accepts a first argument to limit the number of results:

{
  products(first: 10) {
    edges {
      node {
        name
      }
    }
  }
}

You can also filter by other criteria. Check the API documentation for available arguments on each field.

Pagination

The Product Hunt API uses cursor-based pagination. Results are returned in edges and pageInfo fields:

{
  products(first: 10) {
    edges {
      cursor
      node {
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

To get the next page of results, use the after argument with the endCursor from the previous response:

{
  products(first: 10, after: "CURSOR_FROM_PREVIOUS_RESPONSE") {
    edges {
      node {
        name
      }
    }
  }
}

tip

Always check hasNextPage to know if there are more results to fetch. Use the endCursor to request the next page.

Nested fields

GraphQL lets you request nested data in a single query. For example, you can request a product and all its comments:

{
  product(id: "123") {
    name
    comments(first: 10) {
      edges {
        node {
          body
          user {
            name
          }
        }
      }
    }
  }
}

This single query retrieves the product, its comments, and the name of each commenter.

Variables

For dynamic queries, use variables instead of hardcoding values:

curl https://api.producthunt.com/v2/api/graphql \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetProduct($id: ID!) { product(id: $id) { name tagline } }",
    "variables": {
      "id": "123"
    }
  }'

Variables are defined in the query signature (query GetProduct($id: ID!)) and passed separately in the request.

Aliases

Use aliases to request the same field multiple times with different arguments:

{
  topProducts: products(first: 5) {
    edges {
      node {
        name
      }
    }
  }
  recentProducts: products(first: 5, after: "CURSOR") {
    edges {
      node {
        name
      }
    }
  }
}

This query retrieves both top and recent products in a single request.

Error handling

If your query has errors, the API will return an errors field in the response:

{
  "errors": [
    {
      "message": "Field 'invalidField' doesn't exist on type 'Product'"
    }
  ]
}

Check the error message to understand what went wrong and fix your query.

warning

GraphQL errors are different from HTTP errors. A 200 response with an errors field means your request was received but the query had problems. Always check for the errors field in the response.

API explorer

Product Hunt provides an interactive API explorer where you can write and test queries:

API Explorer

The explorer includes documentation for all available fields and arguments, making it easy to discover what data you can query.