Understanding DTOs

When working with GraphQL, specifically Hot Chocolate, in the context of Sage Active Public API V1, it’s essential to understand the role and naming convention of Data Transfer Objects (DTOs). These DTOs facilitate data exchange between client and server and play a critical role in mutations and queries.

General Naming Convention

For each resource, we use a specific naming pattern for the associated DTOs:

• Create operations: CreateGLDtoInput
• Update operations: UpdateGLDtoInput
• Delete operations: DeleteGLDtoInput
• Read operations: GLDto
• List operations: GLDto

For instance, for a resource named AccountingAccount:

• Create: AccountingAccountCreateGLDtoInput
• Update: AccountingAccountUpdateGLDtoInput
• Delete: AccountingAccountDeleteGLDtoInput
• Read: AccountingAccountGLDto
• List: AccountingAccountGLDto

The Role of DTOs in Mutations

Create Mutation Example

For creating a new resource, you will use the CreateGLDtoInput DTO. The following mutation creates a new Journal Type:

mutation ($values: JournalTypeCreateGLDtoInput!) {  
  createJournalType (input: $values) {
    id
  }
}

Update Mutation Example

For updating an existing resource, you’ll use the UpdateGLDtoInput DTO:

mutation ($values: JournalTypeUpdateGLDtoInput!) {  
  updateJournalType (input: $values) {
    id
  }
}

The Role of DTOs in Queries

Queries also make use of DTOs, particularly when fragments are involved. Fragments allow you to create a set of fields and then include them in multiple queries to avoid repetition.

Query with Fragment Example

The following query retrieves a list of users along with specific user properties defined in a fragment:

query {
    users  {
        edges {
            node {
                ...UserProps
            }
        }
        totalCount
        pageInfo {
            hasNextPage
        }
    }     
}

fragment UserProps on UserGLDto {
    id
    fullName
    authenticationEmail
    activeOrganizationId
    applicationLanguageCode
    isBlocked
    hasAllOrganizations
    expirationDate
}

In this example, UserProps is a fragment on UserGLDto, which specifies the user properties we are interested in.

By adhering to these naming conventions and understanding the role of DTOs, you can work more efficiently and maintain a consistent developer experience.