If the save endpoint is exposed to a resource, you can create and update records for that resource.
It expects standard FormData fields to match the resource fields. If the id field is set, an update will occur on the record that matches the id value.
If no id is specified, a new record will be created. The JSON formatted response will include the id of the new record, and if applicable, also the slug.
Example JSON Response:
{
success: true,
record_id: 12,
slug: "asljd234u234"
data: {
record_id: 12,
slug: "asljd234u234"
}
}
Example: JobNote can contain a list of UploadFile records. When a file upload occurs, we may want to associate that file with a JobNote:
UploadFile:
{
id: 4567,
filename: "1234-123.jpg",
original_filename: "cat.jpg",
thumb_filename: "1234-123-thumb.jpg",
...
}
JobNote:
{
id: 1234,
job_id: 789,
subject: 'This is a note',
note: 'This is the note body'
...
}
In order to associate the UploadFile record with the JobNote record, we can make a post request to the /save endpoint like so:
POST /JobNote/save
{
id: 1234,
UploadFile: [4567]
}
This will result in a relationship being established between the two records, and UploadFile can now be queried as an include to JobNote:
POST /JobNote/get?include=['UploadFile']
Response:
{
id: 1234,
job_id: 789,
subject: 'This is a note',
note: 'This is the note body'
UploadFile: [
{
id: 4567,
filename: "1234-123.jpg",
original_filename: "cat.jpg",
thumb_filename: "1234-123-thumb.jpg",
...
}
]
}
IMPORTANT: The array of ids being passed in to establish a relationship represents an exhaustive list. All existing relationships that may exist will be removed, and only what is explicitly declared will be set.
In some cases, there exists a 3-way relationship between records. For example, the JobUser resource has a relationship back to Job, a User, and a JobPersonnelRole as well.
We may want to set the users who are assigned to a job, and also ensure they are assigned a role, however that is not possible with a normal sync because a normal sync only accepts a list of record ids. A 3-way sync makes this possible with a request payload like so:
POST User/save
{
id: 17 //user_id,
JobPersonnelRole: {
set: [123, 456], //list of role ids
other_field: "job_id", //the 3rd relationship key field
other_id: 35 //the job_id value
}
}
In the request above, a User with id of 17, will be assigned to the Job that has an id matching 35, and he will be assigned 2 JobPersonnelRoles under that project, matching ids of 123, and 456.
Any validation errors that occur will be returned with field properties and error messages in a response similar to what is shown below. A save has not occured if an error response is returned.
{
success: false,
errors: {
company_name: "The Company Name field is required.",
email: "The Email field is required"
}
}
/save-batch endpoint enables saving multiple records in a single request. It expects a records FormData field, with a JSON array of records:
{
records: [
{
id: 12,
first_name: "Chad"
},
{
id:16,
first_name: "Bob"
}
]
}
Batch saves won't return validation errors, or specific ids for each created records, only a response indicating the number of successful saves that occurred:
{
success: true,
records_saved: 3
}