Entity "update" vs "create" API behavior

[mdeuser]

Looking for UX input regarding the expected behavior of the wsk CLI "update" commands:

1. Update an existing item; create the item if it does not exist -OR-
2. Update an existing item; fail if the item does not exist

The former provides a shortcut way to always make sure a particular item is set the way you want it; while the latter will catch accidental name typos or incorrect expectations.

Currently, the online help describes option (2); however, the actual behavior is (1).

[mdeuser]

I looked at the bluemix cli, bx, for some precedence.

For example, bx service update will fail if the service does not already exist. But, the command options are very difference from the bx service create command, so it was not really intended to "create if not exist".

[csantanapr]

I have this issues in past CLI projects is to have a flag --force for the update command.

Update will fail if asset doesn't exist. If you don't care then use --force to create if doesn't exist

[csantanapr]

Using update and have it fail if the thing your are updating is invalid or doesn't exist is a useful use case. Also on top have the CLI have return codes and human messages indicating why it failed, because of auth, or thing doesn't exist, wrong arguments, etc.

[csantanapr]

I proposed to move forward I vote for #2 and adding -f --force to update command

[rabbah]

Can you help me understand why you want update -f? I'll posit that majority of uses of update will be with -f. The promotion of update to first class was based on user feedback. So if we add -f and it's the common case what justifies adding it?

Also keep in my the semantics of the API. You will need to implement a get then an update to get the semantics proposed. Which is an anti pattern as there can be races - in a shared namespace for example.

[csantanapr]

What was the user feed back? They wanted a simple command to upload new code and create the action if doesn't already exist? My answer would be wsk action update foo foo.js --force I think that would be enough and common to understand. If you want a second alternative then I will do it in create where create will create the action if it doesn't already exist, and it already exist will just continue along update the with the new code.

I don't understand the race condition you are talking about. There is no need for a get first. you let the backend handle it We send single request to update an action, server should respond asset doesn't exit to update. If user uses --force We send a single request to create a new action, server will will create the action if it doesn't exist, or update it if already exist.

[csantanapr]

I want to cover the use case, and it will come up specially from ops folks, that they think they update the code, but it never got update because they misstype the name of the action, all this time they were pulling their hair out on why the system was running the old code and never notice that the update command was creating a new action with slight misspell

wsk create processMyChecks processMyChecks.js

Some later or another person or script

wsk create processmyChecks processMyChecks.js

Why the new code is not fixing the bug 8 hours later... Oh we have two actions with similar names :-(

wsk list
actions
processmyChecks
processMyChecks

[rabbah]

To be clear what you're proposing (the semantics) require an API change (e.g., change ?overwrite to ?update and add ?force). We don't have an operation that does an update only if the entity exists. So either you will need to make an API change or fix it in the CLI to do the check (does it exist) before update. Anytime you have to check before you create you're prone to a race and this is an anti-pattern to avoid.

My point is, regardless of how you implement it, the common case and the deploy scripts we've seen use update not create. So if all those scripts end up doing update -f and there are very few cases of update with the force, there's no good reason to add the f.

What is this change motivated by. Do we have feedback that suggests the current semantics have become or are confusing?

To your use case, and if the same two users did this, what's the gain?

wsk update -f processMyChecks processMyChecks.js

Some later or another person or script

wsk update -f processmyChecks processMyChecks.js

One alternate consideration is to return a different code for created vs update (200 vs 201). This is perhaps least disruptive and allows the CLI or a client to report "created" vs "updated" message. Then it doesn't matter if they update or create, -f or lack there of, you know exactly what happened.

[csantanapr]

That's the point for the use case user wants to use update in a way that will error if the resource doesn't exist, this way they can test their scripts, and they can have confidence that existing actions are updated and script is correct. The purpose of the script and the task to update existing actions, that they deploy and are in production for a while. They will not use force in the case

[starpit]

do these SAT analogies work?

cf create-service is to wsk action create as new HashMap is to map.put

cf update-service is to wsk action update as map.put is to map.put

i.e. an update-serivce is meaningless unless you've created the container (via create-service). whereas in openwhisk's case, both operations are element-oriented -- one will increase the size of the collection, the other may or may not.

and, whether it does or not... Map.put typically operates as rodric suggests for openwhisk, i.e. the Map.put contract specifies that the return value can be used to determine whether the put changed the size of the collection.

[rabbah]

Proposal to finish off this issue based on above comments: there are three desired behaviors. I'm taking it as a constraint not to disrupt the (v1) API too much hence PUT will continue to mean create or update. As such, we have:

1. PUT: create entity iff doesn't exist else error
2. PUT + ?XXX=true: update entity if it exists, create it otherwise
3. PUT + ?YYY=true: update entity iff it exists, error otherwise

We currently use XXX == overwrite and support only 1-2 and not 3.

• The HTTP response code for 2 should change from 200 to 201 when entity is created instead of updated.

So as not to break uses of overwrite via direct HTTP calls but admit the additional use (3), I propose to repurpose overwrite for 3 and add force for 2. The CLI correspondingly would allow:

• wsk action create (same as 1)
• wsk action update (same as 3 where now it means 2)
• wsk action create --force (same as2`)
• wsk action update --force (same as2`)

The CLI would also alias --force to -f for convenience.

This satisfies @csantanapr (done in the backend) and @mdeuser (don't create on update by default) and preserve convenience for deployment scripts (choice of -f on create or update).

Soliciting thumbs up or down to adopt or reject, comments to refine.

[csantanapr]

@rabbah thanks for the writeup, I agree with proposal

[csantanapr]

remove cli label, added API since API would need to be done first.