Bulk API assumes transactional semantics for changing operations

[enikao]

What should happen if a request to bulk API partially succeeds? Example: We request node ids x, y, and z, but the repository doesn't know y.

What should happen if a request partially fails? Example: We store nodes q, r, s, t, and t as child of both r and s.

Option A: Whole request fails

If any part of the request is unsuccessful, the whole request fails.

Pro:

• Very safe

Con:

• Would need good mechanism to signal which parts failed, e.g. which node id is not known to the repository.

Option B: Request always succeeds, issues are reported back

Pro:

• ?

Con:

• We have implicit semantics (e.g. deleting a node implicitly deletes all its children). A client would need to re-model all implicit semantics to understand the effects of partially successful requests

Option C: Non-modifying requests always succeed, omit missing parts

The first example above would return node x and z.

Pro:

• Simple API

Con: The client needs to compare request and result to figure out that there's no node with id y.

Option D: Modifying requests partially succeed, omit missing parts

The second example above would store node q, and chose the containment for t that's mentioned inside t.

Pro:

• Simple API

Con:

• Even harder for a client to figure out what actually happened than option B

Option E: Modifying requests completely fails, doesn't change the repository, (reports issues back textually)

If any non-recoverable issue arises during a modifying request, the repository does not apply any changes (or rolls back already applied changes from the same request). Such an issue is typically a programming error, so the user cannot deal with it. Thus, we don't need a very structured response, but only a hint to the developer.

[joswarmer]

I think that there are different answers:

Retrieve: option C: A retrieve operation always succeeds, it is perfectly normal that a node cannot be found, as we support e.g. dangling references.

Store option E: I would see a store operation as a transaction, it either succeeds completely or fails completely. It will be quite hard for a client to deal with a partially succeeded store operation. And it might semantically be incorrect to store only part of a request. We do need to report back why it failed, so the client can take appropriate action. It might not be a programming error, but also e.g. consurrent update error.

In what way is option A different from option B?

[dslmeinte]

I think A = E but with a structured failure response so clients can take appropriate measures.

[joswarmer]

Ok, I think that we should always send a structured response. The response when failing should become part of the Bulk API specification.

[enikao]

In what way is option A different from option B?

A would fail if any requested node id is unknown. B would succeed and send back "list of node ids not found: ..."

[enikao]

I think A = E but with a structured failure response so clients can take appropriate measures.

A is about any kind of request, E only about modifying requests

[enikao]

Preliminary decision: We cannot come up with a general rule, need to decide individually per command