Expose replace API endpoints

[Amir-61]

Form @bajtos:

I'd like to discuss the naming scheme for these new methods (replaceOrCreate, replaceAttributes). I feel that replaceAttributes is not describing the intent precisely, and the difference between replaceAttributes and updateAttributes may not be clear enough.

At the moment, we have (among others):

• MyModel.create
• MyModel.updateOrCreate
• myModelInstance.updateAttributes
• myModelInstance.updateAttribute (a single attribute)

I am proposing to come up with new names while we are at adding support for REPLACE operations:

• MyModel.create (remains same)
• MyModel.patchOrCreate (with an alias MyModel.updateOrCreate for backwards-compatibility)
• myModelInstance.patchAttributes (with an alias myModelInstance.updateAttributes for backwards-compatibility)
• myModelInstance.updateAttribute
• MyModel.replaceOrCreate
• myModelInstance.replace or perhaps one of
  • myModelInstance.updateTo
  • myModelInstance.updateAllAttributes
  • myModelInstance.setTo

[Amir-61]

From @bajtos:

@raymondfeng commented in loopbackio/loopback-datasource-juggler#788 (comment):

I prefer to only expose remote endpoints from the static methods replaceById and patchById to avoid 2 calls. The instance methods such as myModelInstance.replaceAttributes/myModelInstance.patchAttributes can be left to the Node.js layer.

I agree, although we need to consider backwards compatibility too.

I am proposing following:

• In 2.x, keep existing mapping for backwards compatibility. Expose replaceById as a new endpoint, e.g. POST /api/Cars/:id/replace. Keep prototype.replaceAttributes hidden from the REST API.
• In 3.x, we should hide prototype.updateAttributes and use static patchById instead.

Note that this change is orthogonal to the second part of this issue, which is exposing replaceById and replaceOrCreate via REST API, preferably at PUT /api/model/:id and PUT /api/model. This second part will require a compatibility flag as we discussed elsewhere.

@raymondfeng @ritch @superkhau @strongloop/loopback-dev @fabien @STRML @clarkorz