Updating records

When it comes to updating records in GraphQL, particularly using Hot Chocolate, the logic closely resembles the concept of the PATCH method in RESTful APIs.

Granular Data Modification

The focus is on modifying only the specific fields that need to be changed, rather than sending the entire dataset.
This approach ensures efficiency and minimizes unnecessary data transfer.

In a typical update, you only need to send the fields that have changed.
This patch-style logic avoids sending unchanged fields, reducing payload size and improving performance.
For example, if you want to update just the vatNumber of a customer, your mutation can be minimal and efficient:

mutation ($values: CustomerUpdateGLDtoInput!) {  
  updateCustomer (input: $values) {
    id
  }
}

{
  "values": {
    "id": "{currentId}",
    "vatNumber": "FR11123456789"
  }
}

However, when dealing with nested sub-resources, such as a customer’s contacts, or the phones belonging to those contacts, the situation becomes more complex.

These nested structures are common in various parts of the API, for example:

In the context of Sage Active Public API V2’s public API, the requestedAction field and the replaceAll flag play a crucial role when updating sub-resources, enabling precise control over whether to modify individual items or replace entire collections.

When dealing with nested sub-resources like contacts or phones, you have two possible strategies:

• You can use a granular patch logic, combining id and requestedAction to add, modify, or delete individual items.
• Or, when it’s simpler to reset everything, you can use the replaceAll flag to fully replace an entire collection, either:
  • at a local level (e.g. all phones of a specific contact), or
  • at a global level (e.g. all contacts of a customer — including their phones, emails, etc.).

This hybrid model — patch by default, with optional replace by reset — allows flexibility depending on what the calling system is capable of providing.

For example, consider the case of updating a customer who has multiple contacts, and each contact has multiple phones.
In a single update operation, you might need to:

• Delete a contact who has left the company
• Create a new contact
• Modify the phone number of an existing contact
• Add or remove phones for specific contacts

All these changes can be expressed together using the requestedAction field or simply relying on the presence or absence of id, as part of a patch-style mutation.

However, if your system does not track precisely what changed, for example, it only knows the final expected list of contacts and phones, then replaceAll becomes a better fit.
In that case, it’s easier to clear the previous values and recreate the full structure in one step. You can apply replaceAll at the appropriate collection level depending on whether you want to reset contacts, phones, or both.

Example using requestedAction

This example demonstrates a patch-style update where:

• The phones of an existing contact are individually updated (modify, delete, create)
• One contact is deleted
• One new contact is added

{
  "id": "{customerId}",
  "contacts": [
    {
      // Modify existing contact's phones
      "id": "{contact1Id}",
      "requestedAction": "MODIFY", // Optional: can be omitted if id is present
      "phones": [
        {
          // Modify phone
          "id": "{phone1Id}",
          "requestedAction": "MODIFY",
          "number": "01 23 45 67 89"
        },
        {
          // Delete phone
          "id": "{phone2Id}",
          "requestedAction": "DELETE" // Required to delete
        },
        {
          // Create new phone
          "requestedAction": "CREATE", // Optional: can be omitted if id is absent
          "number": "06 07 08 09 10",
          "type": "MOBILE"
        }
      ]
    },
    {
      // Delete contact
      "id": "{contact2Id}",
      "requestedAction": "DELETE" 
    },
    {
      // Create new contact
      "requestedAction": "CREATE", 
      "name": "New Contact",
      "phones": [
        {
          "requestedAction": "CREATE", 
          "number": "05 55 55 55 55",
          "type": "LANDLINE"
        }
      ]
    }
  ]
}

Example using replaceAll COMING SOON This feature is currently in development and will be available in the next version. It’s already documented to keep you informed about its upcoming availability

This example replaces the entire list of contacts and their phones:

• All existing contacts are removed
• The list is fully replaced by two new contacts
• Each contact’s phone list is also entirely replaced (no need for replaceAll at phone level since contacts are replaced)

{
  "id": "{customerId}",
  "contacts": {
    "replaceAll": true,
    "items": [
      {
        // Recreate contact "Alice" with new phones
        "name": "Alice",
        "phones": {
          "items": [
            {
              "number": "06 07 08 09 10",
              "type": "MOBILE"
            }
          ]
        }
      },
      {
        // Recreate contact "Bob" with new phones
        "name": "Bob",
        "phones": {
          "items": [
            {
              "number": "01 23 45 67 89",
              "type": "LANDLINE"
            }
          ]
        }
      }
    ]
  }
}

Summary Table: Sub-Resource Update Strategies

requestedAction: Rules and Requirements

When is requestedAction necessary?

• requestedAction: DELETE → Required
  You must explicitly specify this action to delete a sub-resource, along with its id.

• requestedAction: MODIFY or CREATE → Optional
  These are optional because the presence or absence of an id is usually sufficient:

  • With an id → treated as a modification
  • Without an id → treated as a creation

Example: Updating a contact’s phones using requestedAction

Effect:

• The phone with id = {phone1Id} is modified.
• The phone with id = {phone2Id} is deleted.
• A new phone is created.
• The rest of the contact and other phones remain unchanged.

{
  "id": "{customerId}",
  "contacts": [
    {
      "id": "{contactId}",
      "phones": [
        {
          "id": "{phone1Id}",
          "number": "01 23 45 67 89"
        },
        {
          "id": "{phone2Id}",
          "requestedAction": "DELETE"
        },
        {
          "number": "06 07 08 09 10",
          "type": "MOBILE"
        }
      ]
    }
  ]
}

replaceAll: Rules and Requirements COMING SOON This feature is currently in development and will be available in the next version. It’s already documented to keep you informed about its upcoming availability

The replaceAll flag can be used at any level of a nested resource, depending on the desired behavior.

• You can apply replaceAll on a specific sub-resource, such as phones, to replace all the phones of a contact while leaving the rest of the contact unchanged.
• Or you can apply replaceAll on a higher-level collection such as contacts, in which case all contacts are replaced, and each new contact replaces the previous one entirely — including its sub-resources like phones, emails, etc.

In this second case, replaceAll is only required at the top level (e.g. contacts), and you do not need to repeat it for each sub-resource like phones, emails, or socialMedias.

Rules to keep in mind:

• If you apply replaceAll on a sub-resource (like phones), only that specific list is reset.
• If you apply replaceAll on contacts, each contact will be recreated from scratch, including all nested sub-resources.
• If you mix update modes (e.g. patching one contact and replacing another), you must apply replaceAll at the relevant sub-levels (e.g. per-contact phones).
• replaceAll must always be accompanied by an items array with the new values.

Example: Replacing all contacts and their phones

Effect:

• All existing contacts are deleted.
• Each contact is recreated with their own sub-resources (phones, etc.).
• No replaceAll is needed for nested lists, since the contacts themselves are fully replaced.

{
  "id": "{customerId}",
  "contacts": {
    "replaceAll": true,
    "items": [
      {
        "name": "Alice",
        "phones": [
          {
            "number": "06 07 08 09 10",
            "type": "MOBILE"
          }
        ]
      },
      {
        "name": "Bob",
        "phones": [
          {
            "number": "01 23 45 67 89",
            "type": "LANDLINE"
          }
        ]
      }
    ]
  }
}

Example: Replacing only the phones of a specific contact

Effect:

• The contact remains unchanged (e.g. same name, same email, same ID if provided).
• Only the list of phones is fully replaced for that contact.
• replaceAll is applied only at the phones level, since we are not modifying or replacing the contact itself.

This is useful when the external system knows the IDs of the contacts it needs to update, but does not track changes inside their sub-resources like phones.
It simply knows the final expected list of phones and prefers to overwrite the entire list.

{
  "id": "{customerId}",
  "contacts": {
    "items": [
      {
        "id": "{contactId1}",
        "name": "Alice",
        "phones": {
          "replaceAll": true,
          "items": [
            {
              "number": "06 99 88 77 66",
              "type": "MOBILE"
            },
            {
              "number": "01 11 22 33 44",
              "type": "LANDLINE"
            }
          ]
        }
      }
    ]
  }
}