GET entities/:uuid returns 304 after resolve about central-backend HOT 6 CLOSED

I'm starting to feel again that specifying baseVersion in the request body might not be semantic for a PATCH request. In a PATCH request, you're updating an entity with the specified label and data. However, you're not updating the base version of the entity, because entities don't have base versions: base versions are a property of entity versions (a subresource of entities).

What if we specified the base version in a query parameter? That might be more semantic, and it would neatly parallel the force query parameter. That way, every PATCH request would require some query parameter: either force=true or a baseVersion.

Not a strong feeling, just an idea!

from central-backend.

Couple of questions just to make sure I understand:

• Why does that endpoint return an ETag? Is it because of our use of the If-Match header?
• If the ETag changes, will we also need to change our use of the If-Match header?

By the way, I've also filed getodk/central#544, which seems thematically related. The two issues might end up being pretty separate though.

from central-backend.

that's right. Maybe etag is not required at all for GET /entities/:uuid because from frontend we are manually setting If-Match header

from central-backend.

I didn't realize this right away, but this issue is user-facing:

• Navigate to the entity detail page for an entity with a conflict.
• Mark the entity as resolved.
• Refresh the page. The conflict summary box is still shown.

from central-backend.

We discussed this in a meeting today.

Thoughts:

• The ETag is supposed to be opaque. We shouldn't tell API users to specify something in particular for the If-Match header, in case we decide to change the format of the ETag in the future.
• However, if the ETag is opaque, then the only way to specify the If-Match header would be to fetch an individual entity. It'd be nice to be able to fetch the list of entities (the entity OData), then specify If-Match when updating each one (so that ?force=true isn't needed).

Decisions:

• Specify the baseVersion in the request body rather than using an ETag. We don't document the ETag or If-Match headers in the API docs currently, so this isn't a breaking change.
  • Frontend will need to specify this.
• Don't return a bespoke ETag (just the one that Express generates).

Open question:

• Should we return a different error code (a 412) if the user specifies a base version that is not the current version?

To document:

• When you update an entity via the API, you can specify whether you want to mark the conflict as resolved at the same time using the resolve query parameter. The API will reject if there is no conflict.
• If you don't specify ?resolve=true, then you will be able to make an update immediately after someone else marks the conflict as resolved. (You and Alice fetch an entity at the same time, then Alice marks the conflict as resolved, then even without refetching the entity, you will be able to update it.)

from central-backend.

I agree, @matthew-white, a query parameter does feel more expected.

from central-backend.