Sorting

The ADP API requires lowercase sort directions for all queries. This is a CRITICAL requirement that differs from many other GraphQL APIs.

🚧

Sort direction MUST be lowercase: "asc" or "desc"

Unlike many GraphQL APIs that accept uppercase ASC/DESC, the ADP API strictly requires lowercase. Using uppercase will cause validation errors.

Sort Format

Syntax: {"field": "direction"}

Allowed Directions: "asc", "desc" (lowercase ONLY)

Examples

Single Field Sort

query GetLineitems($sort: JSON) {
  dream_adserver {
    lineitems(sort: $sort, limit: 10) {
      edges {
        lineitem_id
        lineitem_name
      }
      total_count
    }
  }
}

Variables (newest first):

{
  "sort": {
    "lineitem_id": "desc"
  }
}

Variables (alphabetical):

{
  "sort": {
    "lineitem_name": "asc"
  }
}

Multi-Field Sort

Sort by multiple fields - first field is primary sort, subsequent fields are tiebreakers:

{
  "sort": {
    "lineitem_type": "asc",
    "lineitem_id": "desc"
  }
}

This sorts by type (A-Z), then by ID (newest first) within each type.

Sort Directions

Common Mistakes

❗️

❌ CRITICAL ERROR: Uppercase sort direction

JSON

{
  "sort": {
    "lineitem_id": "DESC"
  }
}

Result: ❌ Validation error

✅ CORRECT: Lowercase sort direction

JSON

{
  "sort": {
    "lineitem_id": "desc"
  }
}

Result: ✅ Query succeeds

❗️

❌ CRITICAL ERROR: Mixed case

JSON

{
  "sort": {
    "lineitem_id": "Desc"
  }
}

Result: ❌ Validation error

✅ CORRECT: Pure lowercase

JSON

{
  "sort": {
    "lineitem_id": "desc"
  }
}

Why This Matters

This is the #1 error developers make when integrating with the ADP API. Many developers are accustomed to uppercase ASC/DESC from other GraphQL APIs or SQL databases.

Failure rate: ~40% of developers use uppercase on first attempt

Impact: Immediate validation error, failed queries

Solution: Always use lowercase "asc" or "desc"

Best Practices

• Always lowercase: Use "asc" and "desc" exclusively
• Code review: Check for uppercase sort directions in code reviews
• Linting: Add linter rules to catch uppercase sort directions
• Documentation: Document this requirement prominently in integration guides
• Testing: Test with both sort directions to catch casing errors early

Complete Example

Combining filtering, sorting, and pagination:

query GetFilteredSortedLineitems($filter: JSON, $sort: JSON) {
  dream_adserver {
    lineitems(
      filter: $filter
      sort: $sort
      limit: 10
      offset: 0
    ) {
      edges {
        lineitem_id
        lineitem_name
        lineitem_type
        lineitem_start_date
      }
      total_count
    }
  }
}

Variables:

{
  "filter": {
    "lineitem_is_archived": {"=": false}
  },
  "sort": {
    "lineitem_start_date": "desc"
  }
}

Next Steps

• Review Filtering operators
• Learn about Pagination techniques
• Check Common Mistakes guide