[Specifications] Separating GET and PUT requests (a'la CQRS) (#234)

tpluscode has just created a new issue for https://github.com/HydraCG/Specifications:

== Separating GET and PUT requests (a'la CQRS) ==
## Describe your API requirement

In a recent project I have been implementing some resource endpoints which, in order to save requests, embed representations off linked resources. For example, a book and a cover could be separate resources

```turtle
# /book/foo
</book/foo> a </api/Book> , schema:Book ; schema:image </image/foo> .

# /image/foo
</image/foo> a schema:ImageObject ; schema:contentUrl <https://s3...> .
```

In order to reduce the required roundtrips (think a collection of books + a request for every book's image) I would prefer to embed those images. Same for a singular `GET /book/foo`

## The problem

The issue is, that when a client gets a book representation with image embedded, how do they request an update? How would they know that the `schema:image` should be omitted from a `PUT` request?

In the case of an embedded property, it could be annotated, for example with `sh:ignoredProperty` but this imposes limitations. How would I distinguish between embedded resource from a resource which is in fact integral part of the `Book`? 

A similar case could be with inferenced types. The `</api/Book>` above could be subclass of `schema:Book`, so that the latter is not explicitly stored in the database about book instances. Thus, it also should not be part of the update request either, in order to prevent materialising of inferred triples.

## Solution(s)

My current choice is to implement the client so that any time they wish to do an update, they would request a fresh instance using a `Prefer` header, such as `Prefer: return=minimal` or a custom preference

```
GET /book/foo
Prefer: return=minimal
```

This would instruct the server not to include any inferred triples nor embedded resources.

The problem I have with this idea is that the client needs to know to make this additional request first. The alternative could be to inject a marker flag into resources which came back with "extra bits" such as 

```turtle
</book/foo> api:representation api:Expanded
```

The server could guard against update which include a `[] api:representation api:Expanded` triple.

Please view or discuss this issue at https://github.com/HydraCG/Specifications/issues/234 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Wednesday, 14 April 2021 07:41:57 UTC