Understanding DTOs

When working with GraphQL, specifically Hot Chocolate, in the context of Sage Active Public API V2, 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.

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

For instance, for a resource named AccountingAccount:

• Create: AccountingAccountCreateGLDtoInput
• Update: AccountingAccountUpdateGLDtoInput
• Delete: AccountingAccountDeleteGLDtoInput

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
  }
}

Delete Mutation Example

For deleting an existing resource, you’ll use the DeleteGLDtoInput DTO:

mutation ($values:AccountingAccountDeleteGLDtoInput!) {
    deleteAccountingAccount(input: $values) {
    id
  }
}

The Role of DTOs in Queries

When defining fragments that previously relied on DTOs, you should now use the actual resource name.
The resource name in the fragment must be in singular form with the first letter capitalized.

For example:

• For a resource named customers, the fragment should be on Customer.
• For a resource named accountingEntries, the fragment should be on AccountingEntry.

Here’s how you should reference resources in your queries:

Query with Fragment Example

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

• REMOVEDThis feature has been removed and will cause a compatibility break if it was previously in use. Fragment: UserProps on UserGLDto

  query {
      users  {
          edges {
              node {
                  ...UserProps
              }
          }
      }     
  }
  
  fragment UserProps on UserGLDto {
      fullName
      authenticationEmail
  }
  

• NEWNew Feature Recently Added. (Introduced in the last version as well as in the previous version) Fragment UserProps on User

  query {
      users  {
          edges {
              node {
                  ...UserProps
              }
          }
      }     
  }
  
  fragment UserProps on User {
      fullName
      authenticationEmail
  }