search

shapetrees / specification

Specification for Shape Trees
https://shapetrees.org
Other
12 stars 5 forks source link

What does the server need? #37

Open kjetilk opened 3 years ago

kjetilk commented 3 years ago

I've read through the spec dated 2021-01-05, and the main thing that was hard to discern throughout the spec is to answer the question "what does server implementations need to do in order to support Shape Trees that lies beyond the Solid Protocol?"

I would myself prefer the answer to that question to be "nothing much". :-) Anyway, I'll just dump my initial impression on you, take it as you wish:

There are a few places where it seems to break orthogonality for no good reason, for example, when it in section 3.2.5.1 mandates a 404 response when the protocol recommends a 410 response in some situations. It would be much better to merely reference the protocol in such situations.

In other situations, e.g. section 3.2.5.4, it operates with POST and PUT, names things via Slug. This should be covered in the protocol, and thus a reference there would be better. If Shape Trees result in specific requirements that aren't covered, then I think it is better to raise it so that it gets into the protocol.

One example of this seems to be the 422 error. I think that would be better served if we had a validation section in the protocol where some classes of validation failures would be detailed, and Shape Trees referenced that.

There are some situations where I get confused, for example in Section 4.1, where it says that the operation may be performed by a client, but goes on to require a 422 error code? I may be totally misunderstanding how this is meant to operate, but surely, it doesn't make sense that a client returns an error code...?

So, given some development in the protocol (e.g. around validation), and given what is currently usual protocol behavior, could Shape Trees it doesn't seem to me there isn't a lot that actually would place any burden on server implementations? It seems that the Link header is the main thing, and I see the value of discovery using the HEAD HTTP verb, but could it conceivably be good enough to place that link in the container?

ericprud commented 3 years ago

Most of these seem editorial so I'll wait for PRs. There's are a couple tech choices where I want to at least describe our Plan A.

I've read through the spec dated 2021-01-05, and the main thing that was hard to discern throughout the spec is to answer the question "what does server implementations need to do in order to support Shape Trees that lies beyond the Solid Protocol?"

I would myself prefer the answer to that question to be "nothing much". :-) Anyway, I'll just dump my initial impression on you, take it as you wish:

We depend on something to remember (Resource, Shape Tree) associations to be able to detect bad PUTs/DELETEs. (Maybe later, that will include bad updates because of breakages in dependent resources, but we aren't there yet.)

That something is ideally the server. In that case, the server needs some metadata or auxilliary resource in which to write down that info and find it again when needed. The client doesn't really need access to that aux resource if the information is communicated in Link: headers (though that does make it RO).

In the client case, it's more like a proxy, though probably imlemented as a library that mimics the favored HTTP interface for that platform (e.g. fetch for javascript). In this case, the library can store the aux info however it wants, though it's likely to want to stick it on the server in some sort of aux resource.

There are a few places where it seems to break orthogonality for no good reason, for example, when it in section 3.2.5.1 mandates a 404 response when the protocol recommends a 410 response in some situations. It would be much better to merely reference the protocol in such situations.

In other situations, e.g. section 3.2.5.4, it operates with POST and PUT, names things via Slug. This should be covered in the protocol, and thus a reference there would be better. If Shape Trees result in specific requirements that aren't covered, then I think it is better to raise it so that it gets into the protocol.

One example of this seems to be the 422 error. I think that would be better served if we had a validation section in the protocol where some classes of validation failures would be detailed, and Shape Trees referenced that.

Those seem editorial, i.e. I don't feel compelled to pester you with our vision; but instead suggest issues unless you think you can get to PRs before this issue washed over by the sands of time.

There are some situations where I get confused, for example in Section 4.1, where it says that the operation may be performed by a client, but goes on to require a 422 error code? I may be totally misunderstanding how this is meant to operate, but surely, it doesn't make sense that a client returns an error code...?

In this scenario, the behavior between some calling program (the real client) and the proxy/client/library alluded to above is specified by HTTP. That's a bit unusual (no WebIDL or language bindings) but offers great advantages (no WebIDL or language bindings). In this regard, the real client doesn't need to know whether ShapeTrees is supported by the server or by a proxy/client/library beyond allowing the proxy/client/library to intercept all of its web traffic to that POD.

So, given some development in the protocol (e.g. around validation), and given what is currently usual protocol behavior, could Shape Trees it doesn't seem to me there isn't a lot that actually would place any burden on server implementations? It seems that the Link header is the main thing, and I see the value of discovery using the HEAD HTTP verb, but could it conceivably be good enough to place that link in the container?

Let's use #38 to hash out the container vs. HTTP issue. (I'll go rename it, presuming your acquiescence or resignation but you can rename it back.)

kjetilk commented 3 years ago

We depend on something to remember (Resource, Shape Tree) associations to be able to detect bad PUTs/DELETEs. (Maybe later, that will include bad updates because of breakages in dependent resources, but we aren't there yet.)

That something is ideally the server.

Yeah, I agree! It feels like there should be something generic in the protocol that you can simply reference, though. So, the question is what that generic thing in the protocol should look like.

In the client case, it's more like a proxy, though probably imlemented as a library that mimics the favored HTTP interface for that platform (e.g. fetch for javascript).

Right, OK! That sounds like a reasonable pattern to me.

Those seem editorial,

Yup, but it inflates the ShapeTree spec substantially, and makes it hard to read and get an overview over, and there is also the more substantive issue (even though I agree it is editorial in the end) that it should rather reference the protocol spec rather than say these things itself.