Specify POST

[csarven]

In context of LDP, POST is used to add resources to containers ie. POST to LDPC resource optionally using the Slug header and Link for interaction model(s).

What should be the POST behaviour to target resources that are not LDPCs?

POST /foo/bar

If the target resource exist, what should happen?

If the target resource doesn't exist, what should happen?

What are the effects of interaction model(s) (LDPR and/or LDPC) used in request's Link header?

How should requests to create a resource with the LDP-NR interaction model get handled?

What are the effects without an interaction model?

[acoburn]

I am happy to adjust the Trellis behavior to whatever gets specified here, but I will describe the current behavior in the context of your questions.

What should be the POST behaviour to target resources that are not LDPCs?

If the target resource exist, what should happen?

Respond with 405 Method Not Allowed

What should be the POST behaviour to target resources that are not LDPCs?

If the target resource doesn't exist, what should happen?

Respond with 404 Not Found

What are the effects of interaction model(s) (LDPR and/or LDPC) used in request's Link header?

For a successful request (i.e. /foo/bar is an LDP-C) the link header would define the interaction model for the newly created resource. A successful response will echo that interaction model back to a client in a Link header.

How should requests to create a resource with the LDP-NR interaction model get handled?

The body of the request (the raw byte stream) is used to create the new resource at the location hinted at with a Slug header (or at a server-generated location in the absence of a Slug header). A successful request will respond with the following:

• A Location header pointing to the new resource's URL
• A Link header with the interaction model of the new resource (i.e. LDP-NR)
• A Link header pointing to the location of the corresponding LDP-RS description of this LDP-NR (every LDP-NR has an LDP-RS description)

What are the effects without an interaction model?

The server uses implementation-specific heuristics to assign an interaction model. I.e. if the Content-Type request header is an RDF serialization that is parseable by the server as RDF, the new resource is assigned an LDP-RS interaction model; otherwise, the resource is assigned an LDP-NR interaction model.

[csarven]

Raised by @ericprud ( https://gitter.im/solid/specification?at=5dcd102092a84f79fe6477bb ):

Should a 201 response payload include statements related to adding a new resource to a container eg. mention other created resources (nested containers) and the relations between them, metadata, associated shapes..

[kjetilk]

Indeed, LDP defines POST only for creation, which has always baffled me, since "Annotation existing documents; [...] Extending a document during authorship." has been part of POST semantics since the dawn of ages. Especially with RDF, where append is clearly defined in terms of RDF Merge (which is basically just a union where you relabel blank nodes so that they don't crash). I think it is important that we do better than LDP in this area, because POST-to-append is very common practice (though, I might have lost touch with devs). Moreover, it seems to me that POST operations will only need acl:Append privileges (with minor exceptions), as they all append operations, right?

So, my proposal follows somewhat like the setup of #40 :

• Container
  • Creation: MUST be supported with Slug as defined elsewhere, with If-None-Match: * also supported.
  • Update: MUST be supported, where the payload is appended to the container representation using RDF Merge but ignores server managed triples. For a HTML representation (Specify/advise semantics of default Container resources (index.html/.ttl) #69), it will replace the HTML, but not the RDF, in which case acl:Write is required.
  • SPARQL Support: Currently discussed in Level of SPARQL Update support #125 .
• RDF source
  • Creation: MUST be supported with Slug as defined elsewhere, with If-None-Match: * also supported.
  • Update: MUST be supported, where the payload is appended to the representation using RDF Merge.
  • SPARQL Support: Currently discussed in Level of SPARQL Update support #125 .
• Non-RDF Source:
  • Creation: MUST be supported with Slug as defined elsewhere, with If-None-Match: * also supported.
  • Update: MAY be supported if the server is able to support an append operation on the media type.
• ACL resources
  • Like RDF sources, but with acl:Control required instead of acl:Append.

[csarven]

For a HTML representation (#69), it will replace the HTML, but not the RDF, in which case acl:Write is required.

By "RDF", are you referring to server-managed triples or the other representations of the same resource?

Why [POST] "replace" exactly? RDF Source or Non-RDF Source Update cases use append.

Requiring different access modes, depending on Content-Type and optionally Link headers, seems awkward. Is there even a way to set a policy like that in ACL? Otherwise, setting acl:Write on the container (and by default its members) just so that it can be updated in HTML seems problematic.

Besides those concerns, I agree with the setup.

[kjetilk]

For a HTML representation (#69), it will replace the HTML, but not the RDF, in which case acl:Write is required.

By "RDF", are you referring to server-managed triples or the other representations of the same resource?

I was thinking the entire RDF representation, to easily distinguish in a non-LDPy way...

Why [POST] "replace" exactly?

Simply because POST is fluffily enough defined to be used this way without breaking a spec... :-)

RDF Source or Non-RDF Source Update cases use append.

Requiring different access modes, depending on Content-Type and optionally Link headers, seems awkward. Is there even a way to set a policy like that in ACL? Otherwise, setting acl:Write on the container (and by default its members) just so that it can be updated in HTML seems problematic.

Yeah, I agree, it is awkward. My thinking is that you would most probably usually replace the HTML representation (#69 ), editions is managed client side, so you GET the resource, make your edits and replace the resource... So, you'd want PUT really, but since you can never replace the whole representation because of the server-managed triples, you can't have PUT, so I gave POST this role instead...

If we resolve that you can replace an HTML representation through PUT (#40) without touching the RDF or at least the server managed triples, then this can go. I'm not sure which is the lesser of evils.

[csarven]

I was thinking the entire RDF representation, to easily distinguish in a non-LDPy way...

I don't understand. Can you please clarify?

Yeah, I agree, it is awkward.

If representations have their URLs, it would be possible to set different access modes. However, the direction we are taking sets the policy on the effective request URI which applies to all representation URLs.

Simpler to keep all POST updates to append.

I'm not sure which is the lesser of evils.

I don't see the key difference. Both approaches essentially attempt to replace a container that way. Looking at it from the other direction, if so desired, the same rule can be applied to POST, PUT, PATCH ie. don't allow server-managed triples to be altered, irrespective of the mediatype. Possible to just ignore or fail universally.

[kjetilk]

I was thinking the entire RDF representation, to easily distinguish in a non-LDPy way...

I don't understand. Can you please clarify?

OK. If we say "server-managed triples" that references the LDP specification, an implementation has to understand what is meant by that, if we say "entire RDF representation", that's just a media type, much less to understand. However, I suppose what makes the actual complexity is something we will find out when we write the spec, it is thus something we can defer until the drafting phase.

Yeah, I agree, it is awkward.

If representations have their URLs, it would be possible to set different access modes. However, the direction we are taking sets the policy on the effective request URI which applies to all representation URLs.

My main concern is that the security usability around access modes for different representation URLs is going to be really bad unless we put a lot of effort into it. We then have to make sure the end result when managing authz isn't confusing. That's not to say that we shouldn't resolve #109 , it is just that it is a much bigger topic when authz is involved. If we just have the container URL, and all manipulations are on that, it is much easier, you know exactly what rules apply.

Simpler to keep all POST updates to append.

I'm not sure which is the lesser of evils.

I don't see the key difference. Both approaches essentially attempt to replace a container that way. Looking at it from the other direction, if so desired, the same rule can be applied to POST, PUT, PATCH ie. don't allow server-managed triples to be altered, irrespective of the mediatype. Possible to just ignore or fail universally.

The key difference is that PUT expects to replace everything, whereas POST doesn't.

[csarven]

If we just have the container URL, and all manipulations are on that, it is much easier, you know exactly what rules apply.

So we agree. Shouldn't design to have representations with different access modes.

The key difference is that PUT expects to replace everything, whereas POST doesn't.

I meant beyond the literal difference between POST and PUT. If POST HTML is spec'd to act like a write/replace operation, it will generally have the same affect as PUT anything to write/replace. And so they both have to deal with not touching the RDF/server-managed triples.

[csarven]

Create a new resource in / (root container):

POST /

<> rdfs:label "foo".

201
Location: /foo

It is not possible to append information to / with POST. Must use PUT or PATCH to change the state of /.

Create /foo/ or append to /foo/ if exists:

POST /
Slug foo/

<> rdfs:label "foo".

Slug is required in order to append information to container with POST.