Working with GraphQL

This guide covers practical patterns for working with the primaTime GraphQL API, including queries, mutations, variables, and common workflows.

GraphQL Fundamentals

Queries vs Mutations

• Queries — Read data (idempotent, can be cached)
• Mutations — Create, update, or delete data (side effects)

# Query - fetching data
query {
  projects(first: 10) {
    edges {
      node { id title }
    }
  }
}

# Mutation - modifying data
mutation {
  createProject(data: { ... }) {
    project { id }
    errors { value }
  }
}

Using Variables

Always use variables for dynamic values:

# Define operation with variables
query GetProject($id: ID!) {
  project(id: $id) {
    id
    title
    code
    status { title }
  }
}

Variables object:

{
  "id": "project_abc123"
}

Request Selection

Only request the fields you need to optimize performance:

# Good - request only needed fields
query {
  projects(first: 10) {
    edges {
      node {
        id
        title
        status { title type }
      }
    }
  }
}

# Avoid - requesting everything
query {
  projects(first: 10) {
    edges {
      node {
        id
        title
        code
        description
        type
        status { id title type color }
        client { id title code }
        workflow { id }
        board { id }
        # ... many more fields
      }
    }
  }
}

Mutation Patterns

Updating an Entity

Full update (all fields required):

mutation UpdateProject($id: ID!, $data: ProjectInput!) {
  updateProject(id: $id, data: $data) {
    project {
      id
      title
      code
    }
    errors { value }
  }
}

Partial Update (Patch)

Only update specific fields:

mutation PatchTask($id: ID!, $data: TaskPatchInput!) {
  patchTask(id: $id, data: $data) {
    task {
      id
      title
      priority
      status { title }
    }
    errors { value }
  }
}

Variables (only changed fields):

{
  "id": "task_abc",
  "data": {
    "priority": "HIGHEST",
    "status": { "id": "status_done" }
  }
}

Batch Operations

Many mutations support batch operations:

# Archive multiple projects
mutation ArchiveProjects($ids: [ID!]!) {
  archiveProjects(ids: $ids) {
    status
    errors { value }
  }
}

# Patch multiple time records
mutation BatchPatchTimeRecords($ids: [ID!]!, $data: TimeRecordPatchInput!) {
  patchTimeRecords(ids: $ids, data: $data) {
    status
    errors { value }
  }
}

Working with Tags

Tags use a patch pattern for modifications:

mutation UpdateProjectTags($id: ID!) {
  patchProject(id: $id, data: {
    tags: {
      add: { values: ["tag_new1", "tag_new2"] }
      remove: { values: ["tag_old"] }
    }
  }) {
    project {
      id
      common {
        tags { id title color }
      }
    }
  }
}

# Replace all tags
mutation ReplaceProjectTags($id: ID!) {
  patchProject(id: $id, data: {
    tags: {
      replaceWith: ["tag_1", "tag_2", "tag_3"]
    }
  }) {
    project { id }
  }
}

Custom Scalars

The API uses custom scalar types:

Scalar	Format	Example
DateTime	ISO 8601 with timezone	2024-01-15T09:30:00.000+01:00
Date	ISO 8601 date	2024-01-15
Time	ISO 8601 time	09:30:00.000+01:00
Color	Hexadecimal	#FF5733
Percentage	0.0000 to 1.0000	0.7500