Common Mistakes

Learn the 4 CRITICAL errors that trip up developers when integrating with the ADP API - and how to avoid them.

Error #1: Uppercase Sort Directions (CRITICAL)

Severity: 🔴 CRITICAL - Causes immediate validation error
Frequency: 40% of developers make this mistake

❌ WRONG

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

Error Message:

{
  "errors": [
    {
      "message": "Invalid sort direction. Must be 'asc' or 'desc' (lowercase)"
    }
  ]
}

✅ CORRECT

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

Why This Happens

Most GraphQL APIs and SQL databases accept uppercase ASC/DESC. The ADP API is different - it strictly requires lowercase.

How to Avoid

• Always lowercase: Use "asc" and "desc" exclusively
• Code review: Check for uppercase in pull requests
• Linting: Add rules to catch uppercase sort directions
• Testing: Test both directions in integration tests

Error #2: Using node Wrapper in Connections (HIGH)

Severity: 🟠 HIGH - Query fails to return data
Frequency: 35% of developers make this mistake

❌ WRONG

query {
  dream_adserver {
    lineitems(limit: 10) {
      edges {              # ← WRONG: node wrapper not used
          lineitem_id
          lineitem_name
        }
    }
  }
}

Error Message:

{
  "errors": [
    {
      "message": "Cannot query field 'node' on type 'DASLineitem'"
    }
  ]
}

✅ CORRECT

query {
  dream_adserver {
    lineitems(limit: 10) {
      edges {               # ← CORRECT: direct access
        lineitem_id
        lineitem_name
      }
      total_count
    }
  }
}

Why This Happens

Standard GraphQL Relay connections use edges { ... }. The ADP API uses a custom Connection structure without the node wrapper.

Connection Structure Comparison

How to Avoid

• No node wrapper: Access fields directly in edges
• Use total_count: Not totalCount or pageInfo
• Snake case: All field names use snake_case

Error #3: Inline JSON in GraphQL (CRITICAL)

Severity: 🔴 CRITICAL - Query syntax error
Frequency: 25% of developers make this mistake

❌ WRONG

query {
  dream_adserver {
    lineitems(
      filter: $filter}    # ← WRONG: inline JSON
    ) {
      edges {
        lineitem_id
      }
    }
  }
}

Error Message:

{
  "errors": [
    {
      "message": "Syntax Error: Expected Name, found {",
      "locations": [{"line": 3, "column": 15}]
    }
  ]
}

✅ CORRECT

query GetLineitems($filter: JSON) {
  dream_adserver {
    lineitems(filter: $filter) {
      edges {
        lineitem_id
        lineitem_name
      }
    }
  }
}

Variables:

{
  "filter": {
    "lineitem_type": {"=": "DISPLAY"}
  }
}

Why This Happens

GraphQL does not support inline JSON syntax. All JSON-type parameters (filter, sort) must be passed as variables.

How to Avoid

• Always use variables: For filter, sort, and any JSON parameter
• Define variable types: $filter: JSON, $sort: JSON
• Pass in variables object: Separate from query

Complete Example

Query:

query GetFilteredLineitems($filter: JSON, $sort: JSON, $limit: Int) {
  dream_adserver {
    lineitems(
      filter: $filter
      sort: $sort
      limit: $limit
    ) {
      edges {
        lineitem_id
        lineitem_name
        lineitem_type
      }
      total_count
    }
  }
}

Variables:

{
  "filter": {
    "lineitem_type": {"=": "DISPLAY"},
    "lineitem_is_archived": {"=": false}
  },
  "sort": {
    "lineitem_id": "desc"
  },
  "limit": 10
}

Error #4: Missing Domain Root Field (CRITICAL)

Severity: 🔴 CRITICAL - Query completely fails
Frequency: 20% of developers make this mistake

❌ WRONG

query {
  lineitems(limit: 10) {        # ← WRONG: missing domain wrapper
    edges {
      lineitem_id
    }
  }
}

Error Message:

{
  "errors": [
    {
      "message": "Cannot query field 'lineitems' on type 'Query'"
    }
  ]
}

✅ CORRECT

query {
  dream_adserver {              # ← CORRECT: wrapped in domain
    lineitems(limit: 10) {
      edges {
        lineitem_id
        lineitem_name
      }
    }
  }
}

Why This Happens

The ADP API uses domain-based organization with 8 root fields. All operations must be wrapped in the appropriate domain.

Domain Root Fields

How to Avoid

• Always wrap queries: Use appropriate domain root field
• Check schema: In Playground, see which domain each operation belongs to
• Follow examples: All documentation examples show correct structure

Additional Common Mistakes

Mistake #5: Direct Filter Values

❌ WRONG:

{
  "filter": {
    "lineitem_type": "DISPLAY"    # ← Missing operator
  }
}

✅ CORRECT:

{
  "filter": {
    "lineitem_type": {"=": "DISPLAY"}    # ← Operator-based
  }
}

See Filtering for details.

Mistake #6: String Boolean Values

❌ WRONG:

{
  "filter": {
    "lineitem_is_archived": {"=": "false"}    # ← String
  }
}

✅ CORRECT:

{
  "filter": {
    "lineitem_is_archived": {"=": false}    # ← Boolean literal
  }
}

Mistake #7: Using hit Instead of edges

❌ WRONG:

lineitems {
  hit {                 # ← Wrong array field name
    lineitem_id
  }
}

✅ CORRECT:

lineitems {
  edges {               # ← Correct array field name
    lineitem_id
  }
}

Mistake #8: camelCase Field Names

❌ WRONG:

lineitems {
  edges {
    lineitemId          # ← camelCase
    lineitemName
  }
}

✅ CORRECT:

lineitems {
  edges {
    lineitem_id         # ← snake_case
    lineitem_name
  }
}

Quick Reference Checklist

Before submitting your first API call, verify:

• ✅ Sort directions are lowercase ("asc", "desc")
• ✅ No node wrapper in Connections (direct access in edges)
• ✅ JSON parameters use GraphQL variables (not inline)
• ✅ Queries wrapped in domain root field (dream_adserver, report, etc.)
• ✅ Filters use operator syntax ({"=": value})
• ✅ Boolean values are literals (true/false, not strings)
• ✅ Array field is edges (not hit or nodes)
• ✅ Field names use snake_case (not camelCase)

Error Prevention Tools

1. Use the Playground

Test queries in the Playground before coding:

https://adp-api.dreamlab.pl/playground

• Auto-complete: Shows available fields
• Validation: Catches errors before execution
• Schema docs: Browse correct field names

2. Code Templates

Use these templates to start correctly:

Basic Query Template:

query GetData($filter: JSON, $sort: JSON, $limit: Int, $offset: Int) {
  dream_adserver {
    [OPERATION](
      filter: $filter
      sort: $sort
      limit: $limit
      offset: $offset
    ) {
      edges {
        [FIELDS]
      }
      total_count
    }
  }
}

Variables Template:

{
  "filter": {
    "[field]": {"=": "[value]"}
  },
  "sort": {
    "[field]": "desc"
  },
  "limit": 10,
  "offset": 0
}

3. Validation Checklist

Before deploying:

1. Test with Playground
2. Verify all 4 critical patterns
3. Check error handling
4. Test with real data (Demo Network: 7012768)
5. Code review by another developer

Impact on Success Metrics

Avoiding these mistakes directly impacts your integration success:

Following this guide gets you there!

Next Steps

Now that you know what to avoid:

1. Explore Delivery APIs - Manage campaigns confidently
2. Review Field References - Master filtering, sorting, pagination
3. Query Line Items - Start with real operations
4. Learn Reporting - Generate campaign reports

Need Help?

If you encounter errors:

1. Check this guide first
2. Test in Playground to isolate issue
3. Review GraphQL Overview
4. Contact [email protected]

Remember: 95% of integration errors are caused by these 4 mistakes. Master them and you'll integrate successfully!