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 within the record, rather than sending the entire dataset.
This approach ensures efficiency and minimizes unnecessary data transfer.

In the context of Sage Active Public API V2’s public API, the requestedAction field plays a crucial role.
This field allows you to specify the type of modification required for a sub-resource.

For instance, when you want to modify, delete or add a sub-resource, you can set the requestedAction accordingly.
This granular approach enables you to precisely control the updates you wish to perform.

Updating Customer Record with updateCustomer Mutation

In this illustrative example of using the updateCustomer mutation, the requestedAction field is strategically employed to specify precise modifications for each sub-resource.
This method aligns with the principles of GraphQL’s patch-like logic, allowing you to achieve targeted updates effectively.

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

{
   "values":{
      "id":"",
      "socialName":"CUSTOMER01_SN MODIFY",
      "tradeName":"CUSTOMER01_TN MODIFY",
      "addresses":[
         {
            "id":"{custAddressId}",
            "requestedAction":"MODIFY",
            "firstLine":"Rue tête d'Or MODIFY"
         }
      ],
      "contacts":[
         {
            "id":"{custContacts0Id}",
            "requestedAction":"MODIFY",
            "isDefault":false,
            "name":"DefaultMODIFY",
            "phones":[
               {
                  "id":"{custContacts0Phones1Id}",
                  "requestedAction":"MODIFY",
                  "number":"0123456789",
                  "type":"MOBILE"
               },
               {
                  "requestedAction":"CREATE",
                  "number":"987654321",
                  "type":"MOBILE"
               }
            ],
            "emails":[
               {
                  "id":"{custContacts0Emails0Id}",
                  "requestedAction":"MODIFY",
                  "emailAddress":"[email protected]",
                  "usage":"EMPTY"
               }
            ],
            "socialMedias":[
               {
                  "id":"{custContacts0SocialMedias0Id}",
                  "requestedAction":"MODIFY",
                  "name":"MODIFY",
                  "link":"www.modify.com"
               },
               {
                  "id":"{custContacts0SocialMedias1Id}",
                  "requestedAction":"DELETE"
               }
            ]
         }
      ]
   }
}

When requestedAction isn’t Necessary

It’s important to note that not every update requires the requestedAction field.
For fields that are directly being modified without impacting other sub-resources, you can directly include them in the mutation without using requestedAction.
This simplifies the process and reduces the need for additional properties.
For instance update the socialName and the tradeName of a customer.

{
  "id": "{customerId}",
  "socialName": "CUSTOMER01_SN MODIFY",
  "tradeName": "CUSTOMER01_TN MODIFY"
}

Using requestedAction for Modifications

When you want to modify a specific sub-resource, such as an address, the requestedAction field comes into play.
Set it to MODIFY to indicate that this sub-resource needs to be updated.
This granular approach ensures that only the specified changes are applied without affecting other parts of the record.
For example update an address of a customer :

{
  "id": "{custAddressId}",
  "requestedAction": "MODIFY",
  "firstLine": "Rue tête d'Or MODIFY"
}

Using requestedAction for Deletions

If you intend to delete a sub-resource, set the requestedAction field to DELETE.
This tells the server to remove the specified sub-resource while keeping the rest of the record intact.
For example delete a socialMedia for a contact of a customer :

{
  "id": "{custContacts1SocialMedias1Id}",
  "requestedAction": "DELETE"
}

Adding Elements to Sub-Resources using requestedAction

In scenarios where you need to add an element to a sub-resource during a modification, the requestedAction field becomes essential.
By setting the requestedAction to CREATE, you indicate to the server that you want to create a new element within the sub-resource while leaving the rest of the record unchanged.

For instance, consider the example of adding a new phone number to a contact’s collection of phone numbers:

{
  "requestedAction": "CREATE",
  "number": "987654321",
  "type": "MOBILE"
}

A Balancing Act

The use of requestedAction offers a balancing act between precision and efficiency.
It ensures that your modifications are targeted and focused, enabling you to work with individual sub-resources while keeping the broader record intact.
This approach aligns with the GraphQL philosophy of selective updates, enhancing data management and developer experience.