Semantics of put operation

[benkehoe]

The put lifecycle section says put "used to create[s] a resource using identifiers provided by the client". This is a slightly different definition from HTTP PUT, which says that "the state of the target resource [is] created or replaced" (emphasis mine).

The put operation can be idempotent but not satisfy HTTP PUT semantics. The SQS CreateQueue API is one such example. It only creates queues, it does not update them, but it is idempotent: If you send multiple requests with the same input and a queue did not exist, or a queue with identical properties exists, you'll receive back the queue information every time. If you send multiple requests with the same input and a queue with different properties exists, you'll receive an error every time.

Is the Smithy put operation supposed to match HTTP PUT's semantics, or something closer to SQS CreateQueue?

[mtdowling]

The put lifecycle works like an HTTP PUT, it just doesn't mandate that a service supports replacing an existing resource. As it's defined now, that's an implementation detail of the service.

We need to model our existing APIs that support idempotently creating resources using client provided identifiers but don't necessarily support replacing them (like DynamoDB tables)... We could add a trait to resources to indicate this kind of special case (for example, @noReplace). Would that clear this up more, or is calling it "put" always going to be confusing?

Do you have a use case in mind where this distinction would be important?

[benkehoe]

I guess at a minimum having the documentation explain that would be good. I do like the idea of @noReplace as validation checks for put operations on a service could verify that replace did or didn't work depending on the presence or absence of the tag.

I didn't have a use case in mind, I just didn't understand from the docs what the intention/semantics were.

[mtdowling]

The @noReplace trait was added, and I added more information to clarify the semantics of the put lifecycle operation.

Thanks for your feedback!