# 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:

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

### Pagination
All queries use cursor-based pagination:

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

### Filtering
Apply filters to narrow results:

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

### Sorting
Sort results by one or more fields:

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

### Formatting
Control how field values are returned:

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

## Next Steps
1. [Set up authentication](https://developer.finaleinventory.com/reference/graphql-authentication) to access the API
2. [Run your first query](https://developer.finaleinventory.com/reference/graphql-getting-started) to fetch data
3. Explore available collections in the sidebar navigation
4. Learn about [core concepts](https://developer.finaleinventory.com/reference/graphql-view-connections) in detail
  
Updated 9 months ago