I think that if you include the ID in the url, you are replacing properties of an existing model:
PUT ~/modelName/{id}/
{
// model data goes here. Everything here updates in the database, but the ID stays the same
}
If you include the ID in the body of the PUT, loopback will attempt to update the model or create a new one if it does not find it:
PUT ~/modelName/
{
id: 'instance id' // update existing model with new data or create new model with this ID
// rest of the data goes here
}
When the documentation says "replace an existing model" what I they mean is "update an existing mode's data, but keep the ID". There is no method to create a new model with a new id and delete an old one all in a single command.
I hope that helps.