Context

The shift from specific <object>ById queries to more generalized <object> queries with a where clause for ID filtering marks an significative change in the Sage Active Public API V2.
This new approach streamlines the querying process and aligns with the overall GraphQL philosophy.

Advantages of the Change

• Reduces the number of <object> types needed for list retrieval and individual record fetching, eliminating the need for a separate <object>ById object.
• Enhances consistency with GraphQL’s general logic.
• Improves performance, as <object> filtered by Id queries are faster than <object>ById.
• Introduces a unified response format using edges and node, enhancing data consistency.
  Previously, responses varied between the specific ById format and other query structures.
  Now, all responses follow the same pattern, simplifying data parsing and handling across different queries.
  This unified format aligns better with the typical GraphQL response structure, making it more intuitive for developers.

Recommendation

Since <object>ById queries have been removed, using the new ID-filtered queries is necessary to maintain functionality and ensure future compatibility.

Example: Transitioning from accountingAccountById to ID-Filtered Query

• REMOVEDThis feature has been removed and will cause a compatibility break if it was previously in use. Query: accountingAccountById

  query ($id: ID!) {
    accountingAccountById(id: $id) {
      id
      accountLevel
      accountType
      code
      subAccountType
      description
      taxTreatmentId
    }
  }
  

  GraphQL variables:

  {
    "id": "{currentId}"
  }
  

• NEWNew Feature Recently Added. (Introduced in the last version as well as in the previous version) ID-Filtered Query accountingAccounts

  query ($id: UUID!) {
    accountingAccounts(where: { id: { eq: $id }}) {
      edges {
        node {
          id
          accountLevel
          accountType
          code
          subAccountType
          description
          taxTreatmentId
        }
      }
    }
  }
  

  GraphQL variables:

  {
    "id": "{currentId}"
  }
  

Response Format Changes

The transition from ById to filtered by Id queries in the latest API version brings a notable change in the response format.

The ById queries returned a direct object under the ‘data’ field.

• REMOVEDThis feature has been removed and will cause a compatibility break if it was previously in use. Response Format (ById):

  {
      "data": {
          "accountingAccountById": {
              // ... fields ...
          }
      }
  }
  

  REMOVEDThis feature has been removed and will cause a compatibility break if it was previously in use. JavaScript Example:

  let accountId = response.data.accountingAccountById.id;
  

• NEWNew Feature Recently Added. (Introduced in the last version as well as in the previous version) Response Format (Filtered by Id):

  With filtered by Id, the response nests the object inside ‘edges’, then ‘node’.

  {
      "data": {
          "accountingAccounts": {
              "edges": [
                  {
                      "node": {
                          // ... fields ...
                      }
                  }
              ]
          }
      }
  }
  

  NEWNew Feature Recently Added. (Introduced in the last version as well as in the previous version) JavaScript Example:

  let accountId = response.data.accountingAccounts.edges[0].node.id;
  

Exceptions

Since specific <object>ById queries have been removed and replaced by generalized <object> queries with an ID filter in the Sage Active Public API V2, this change applies universally without exceptions.

• Actions Related to the ID of an Object
  Certain actions are intrinsically linked to the ID of a specific object.
  For example, ProductPrice only offers the productPriceById query. API resources overview / ⚙️Product Price service
  These actions are tailored to operate uniquely with individual IDs and do not conform to the generalized list query format.
  As such, they remain as standalone queries, ensuring precise and direct access to the specific data needed for these unique actions.