Atomic Operations and inclusion of related resources

[tobyzerner]

I'm currently working on an implementation of the Atomic Operations extension on both the server and client-side.

I'm wondering if there is a way for an operation to request the inclusion of related resources in its response? For example, if one of my operations is to create a resource, can I request the inclusion of resources related to the resource that has just been created?

The spec doesn't appear to say anything about it. I haven't thought about this in a huge amount of detail, but as a starting point, perhaps something like this could be allowed:

POST /operations HTTP/1.1
Host: example.org
Content-Type: application/vnd.api+json;ext="https://jsonapi.org/ext/atomic"
Accept: application/vnd.api+json;ext="https://jsonapi.org/ext/atomic"

{
  "atomic:operations": [{
    "op": "add",
    "href": "/blogPosts?include=author",
    "data": {
      "type": "articles",
      "attributes": {
        "title": "JSON API paints my bikeshed!"
      },
      "relationships": {
        "author": {
          "data": { "type": "users", "id": "1" }
        }
      }
    }
  }]
}

Or perhaps it would be better to introduce a new member which could be used in combination with both ref and href:

{
  "atomic:operations": [{
    "op": "add",
-    "href": "/blogPosts?include=author",
+    "href": "/blogPosts",
+    "include": ["author"],
    "data": {
      ...
    }
  }]
}

The response could look like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json;ext="https://jsonapi.org/ext/atomic"

{
  "atomic:results": [{
    "data": {
      "links": {
        "self": "http://example.com/blogPosts/13"
      },
      "type": "articles",
      "id": "13",
      "attributes": {
        "title": "JSON API paints my bikeshed!"
      },
      "relationships": {
        "author": {
          "data": { "type": "users", "id": "1" }
        }
      }
    },
    "included": [
      {
        "type": "users",
        "id": "1",
        "...": "..."
      }
    ]
  }]
}

[tobyzerner]

Another consideration is that it could also be useful to be able to specify other query parameters, like fields for sparse field sets. So perhaps these could all be wrapped in a params object:

{
  "atomic:operations": [{
    "op": "add",
    "href": "/blogPosts",
    "params": {
      "include": ["author"],
      "fields": {"users": ["name", "email"]}
    },
    "data": {
      // ...
    }
  }]
}

[freddrake]

Another consideration is that it could also be useful to be able to specify other query parameters, like fields for sparse field sets. So perhaps these could all be wrapped in a params object:

It would be good if the specification indicated whether query parameters should be included in the href field; if not, then a side-structure like @tobyzerner's "params" suggestion would be very helpful.

[dgeb]

@tobyzerner thanks for pointing out this oversight. I believe that inclusion of query params in the href member as a means to control the shape of the response document would be inappropriate. Instead I favor the introduction of a params member, which was in the original operations PR. It will need a bit further specificity, as discussed in the comments.