I’m currently working on integration of atomic extension and I’m missing some guidelines in specification.
Is it right that this extension forbids some part of base specification, like data?
What happens to other parts of request like pagination, inclusion, sort, sparse fields etc. Is it forbidden too?
What to do when there are two operations for same resource? Because specification says it must return result for atomic operation, which means I should return resource object in several stages of update if multiple update operations occurs in one request?
Is Ref and URI Path interchangeable? e.g. i have path /authors/123/relationships/comments, which means there is resource type authors, id 123 and relationship comments, is it same as ref with type: authors, id: 123 and relationship: comments?
Thanks for even partial answers. This really bothers my mind nowadays.
Yes. The data and included members are forbidden if atomic operations extension is applied.
Great question!
A server cannot support the include query parameter if the atomic operations extension is applied. If the include query parameter is applied, the included member must be present in the response document. But that’s forbidden by the extension. Supporting the include query parameter would lead to conflicting processing rules.
The same applies to sort query parameter. The base specification requires that primary data in data member must be sorted as requested. But that conflicts with processing rules of the extension which forbids that member.
For sorting, pagination and filtering it does not seem that clearly defined. But I think the intention of the base specification is clearly that those apply to the primary data encoded in data. A server should not support those query parameters if atomic extension operation is applied.
I think this should be clarified in the extension.
I’m not sure on sparse fieldset to be honest. Applying it to the data within an atomic response object seem to make sense. And I don’t see a processing rule within the base spec conflicting with that.
That’s a very good question as well. I fear that case hasn’t been considered when defining the extension. My first intention would be that a server should reject a request if it targets the same resource twice. But that may not prevent the issue entirely. A request could still update a resource and the resource relationships in a same request. And there might be even valid use cases for it. E.g. updating a resource’s attribute and patching a to-many relationship of the same resource in a single request. @dgeb what’s your thoughts on that case?
Assuming that the API follows the recommended URL naming schema: yes.
Accept it or not isn’t the problem. What should be a response in that case? Have to take a snapshots of resource for each operation to satisfy atomicity? Or is it fine just return final state of resource for both operations? This leads to another question. Is it right to have same resource in atomic: results twice or more times?
The atomic operations extension defines the data member of a result object as “the “primary data” resulting from the operation.” So it should be the state of the resource after that specific operation. Not the state of the resource after performing all operations. At least in my reading.
I see that this may complicate client implementations. Those may need to calculate the state of the object after performing all operations.
I just noticed that the atomic operations extension allows targeting the same resource in multiple operations explicitly. An operation object may “target an individual resource that has been assigned a local identity (lid) in a prior operation object.”
Well, that really complicates handling those requests. Because presentation layer just make modifications of business entity and then translate those entities to presentation entity, ergo resource. Making snapshots of business entity is really overhead.
I think this is inconvenient even more if you consider constraint about included data, which tells to include resource only once, even if there are multiple resource identificators. So I have algorithm which checks data to ensure there is resource in full only once. Now even this must be optional.
Anyway thanks for your answers and ideas, I’m gonna try push further with my solution and come back with some production feedback.
P.s. And don’t get me wrong, I’m not here to gripe. I’m very grateful for all your work and effort. Me and my team love the idea of batch operations which atomic try to bring. That’s why I’m so prudent about it. I just want it to works.