search

HydraCG / Specifications

Specifications created by the Hydra W3C Community Group
Other
138 stars 26 forks source link

expectHeader usage #212

Closed rb1193 closed 4 years ago

rb1193 commented 4 years ago

Describe your API requirement

I've been looking for some documentation on the expected usage of the hydra:expectsHeader and hydra:returnsHeader properties, but to no avail. Is any available? I was thinking of potentially using expectsHeader to state that an Authorization header should be provided on protected routes but I am not sure whether that is appropriate.

I'm also surprised that the properties only allow one value (though I don't have a use case for more than one at this point). Can anybody explain why that is?

tpluscode commented 4 years ago

The headers have not really been finalised. Not that its rdfs:range is not defined so it's a little free-form right now

I'm also surprised that the properties only allow one value (though I don't have a use case for more than one at this point).

I don't see that it does. You can have multiple values

{
  "expectsHeader": [ "authorization", "X-Foo" ]
}

Again, the semantics of the values are undefined at this point. Might be string, or maybe something more sophisticated but up to the application to understand the semantics

rb1193 commented 4 years ago

According to the latest draft of the spec it has a range of "xsd:string", unless I'm mistaken?

Is it worth coming up with an idea of a possible spec? I notice that the HTTP in RDF draft spec includes some header classes but I saw in another issue that there was some reluctance to use those definitions in Hydra.

tpluscode commented 4 years ago

Indeed, I looked at the HTML spec and apparently it's not in sync. I that listing is generated from the JSON-LD 🤔. @alien-mcl ?

Is it worth coming up with an idea of a possible spec?

Of course. Let's revisit the previous discussion. What are your specific requirements? What do you need out of the header descriptions?

alien-mcl commented 4 years ago

Indeed, I looked at the HTML spec and apparently it's not in sync. I that listing is generated from the JSON-LD

Well, it should be that way. I'll have to figure it out why it's not working as it should.

I'm also surprised that the properties only allow one value

In RDF you can always come with more values. As @tpluscode provided an example for JSON-LD, you're free to give a set of values. I'd be cautions with RDF lists though.

I notice that the HTTP in RDF draft spec includes some header classes but I saw in another issue that there was some reluctance to use those definitions in Hydra.

We didn't want to stick to HTTP to much. Headers are concept existing in various scenarios thus it felt OK to have it reflected in hydra, but digging deeper within the HTTP specification seemed to much for a generic vocabulary.

I've been looking for some documentation on the expected usage of the hydra:expectsHeader and hydra:returnsHeader properties, but to no avail.

No special examples were provided as it seemed these terms were pretty simple. Each just gives a set of header names either expected or returned by an operation. No more, no less. It's more of a union of all possible header names that can be expected or returned as final set may vary at runtime, depending on various circumstances (i.e. user priviledges, etc.).

Feel free to ask for more details - we'll try to address these requirements of yours.

rb1193 commented 4 years ago

That all makes sense, really all I want to be able to do is provide a set of possible header names as you describe, I was just a bit confused by the "xsd:string" range. I'm still getting to grips with the Hydra and RDF specs, I didn't realise that RDF allows multiple values by default. Thanks for clarifying.