Filtered by Id Instead of ById
Quick Links
Accounts Accounting Entries Products Customers Sales quotes Sales invoices Suppliers Purchase invoicesContext
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.
Notes:
-
If you have already been using a query with a
whereclause to filter by ID for retrieving a record, you won’t need to make any changes.
This method remains effective and in line with the updated querying approach. -
The latest version of the Postman collection has transitioned from using ById queries to filtered by Id for more streamlined and efficient data retrieval. This update aligns with the current best practices in API querying.
Download the new Postman collection and explore the updated features: Quick start / 5. Test your first query in Postman.
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>ByIdobject. - 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
edgesandnode, enhancing data consistency.
Previously, responses varied between the specificByIdformat 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
Query: accountingAccountById
query ($id: ID!) {
accountingAccountById(id: $id) {
id
accountLevel
accountType
code
subAccountType
description
taxTreatmentId
}
}
GraphQL variables:
{
"id": "{currentId}"
}
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.
Response Format (ById):
{
"data": {
"accountingAccountById": {
// ... fields ...
}
}
}
JavaScript Example:
let accountId = response.data.accountingAccountById.id;
Response Format (Filtered by Id):
With filtered by Id, the response nests the object inside ‘edges’, then ‘node’.
{
"data": {
"accountingAccounts": {
"edges": [
{
"node": {
// ... fields ...
}
}
]
}
}
}
JavaScript Example:
let accountId = response.data.accountingAccounts.edges[0].node.id;
Caution
When transitioning from ById to filtered by Id queries, be aware of the change in the ID parameter’s expected type.
Queries that previously accepted ($id: ID!) now require ($id: UUID!).
This change indicates that the API expects a UUID format for unique identifiers, which is more specific and standardized than the generic ID type.
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 theproductPriceByIdquery. API resources / ⚙️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.