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 V1.
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

While <object>ById queries are still functional but deprecated, it is recommended to transition to the new ID-filtered queries for efficiency and future compatibility.

Example: Transitioning from accountingAccountById to ID-Filtered Query

• DEPRECATEDThis object is now deprecated, and we recommend using an alternative solution Query: accountingAccountById

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

  GraphQL variables:

  {
    "id": "{currentId}"
  }
  

• NEWNew Feature Recently Added 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.

• DEPRECATEDThis object is now deprecated, and we recommend using an alternative solution Response Format (ById):

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

  DEPRECATEDThis object is now deprecated, and we recommend using an alternative solution JavaScript Example:

  let accountId = response.data.accountingAccountById.id;
  

• NEWNew Feature Recently Added 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 JavaScript Example:

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

Exceptions

While the transition from specific <object>ById queries to generalized <object> queries with an ID filter is the recommended approach for most resources in the Sage Active Public API V1, there are some exceptions where this rule does not apply:

• accountingPlansMasterById
  This exception exists because there is no List object equivalent for this resource.
  The accountingPlansMasterById remains the primary method for querying specific details of accounting plans, as it does not have a corresponding list query structure. API resources overview / Accounting Plan master
  Therefore, this query maintains its unique status and does not transition to the new ID-filtered format.

• 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.