Introduction to Finale GraphQL API

Overview

The Finale GraphQL API provides a flexible, powerful way to query and interact with your inventory data. Unlike traditional REST APIs that require multiple requests to fetch related data, GraphQL allows you to request exactly the data you need in a single query.

Key Features

Consistent API Structure

All collections follow the same patterns:

• ViewConnection naming: Every collection uses the {name}ViewConnection pattern
• Relay pagination: Standard cursor-based pagination across all queries
• Filtering and sorting: Consistent argument patterns for data manipulation
• Relations: Nested queries for related data in a single request

What You Can Do

• Query inventory data: Products, orders, locations, and more
• Navigate relationships: Fetch related data in a single request
• Filter results: Apply collection-specific filters to narrow results
• Sort data: Order results by one or more fields
• Paginate efficiently: Use cursor-based pagination for large datasets
• Aggregate data: Get summary metrics and grouped statistics
• Format output: Control how field values are formatted (HTML, raw, abbreviated, etc.)

GraphQL vs REST

GraphQL Advantages:

• Fetch exactly what you need (no over-fetching or under-fetching)
• Get related data in one request (no N+1 queries)
• Strongly typed schema with built-in documentation
• Evolution without versioning

When to Use GraphQL:

• Building custom integrations or applications
• Need to fetch related data efficiently
• Want flexible queries without backend changes
• Working with large datasets requiring pagination

When to Use REST:

• Simple CRUD operations
• Existing integrations already using REST
• File uploads/downloads
• Webhook handlers

Core Concepts

ViewConnections

Every collection is accessed via a ViewConnection:

query {
  productViewConnection(first: 10) {
    edges {
      node {
        productId
        sku
      }
    }
  }
}

Pagination

All queries use cursor-based pagination:

query {
  orderViewConnection(first: 50) {
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Filtering

Apply filters to narrow results:

query {
  orderViewConnection(
    first: 10
    type: ["SALES_ORDER"]
    status: ["OPEN"]
  ) {
    edges {
      node {
        orderId
      }
    }
  }
}

Sorting

Sort results by one or more fields:

query {
  orderViewConnection(
    first: 10
    sort: [{ field: "orderDate", mode: "desc" }]
  ) {
    edges {
      node {
        orderId
        orderDate
      }
    }
  }
}

Formatting

Control how field values are returned:

query {
  productViewConnection(first: 10) {
    edges {
      node {
        productId(formatter: "html")  # HTML with links
        sku(formatter: "none")        # Raw value
      }
    }
  }
}

Next Steps

1. Set up authentication to access the API
2. Run your first query to fetch data
3. Explore available collections in the sidebar navigation
4. Learn about core concepts in detail

Updated 9 months ago