Closed lanthaler closed 9 years ago
Note that fixing #25 depends on the outcomes of this: as both properties would map to statusCode
after singularization, they would become indistinguishable.
Therefore, I could either partially fix #25 and leave statusCodes
as plural, or I could rename and then singularize.
To decide on this, let's see what each property is supposed to mean.
The current statusCode
associates a StatusCodeDescription
with an actual HTTP status code. I think that it doesn't make much sense to express that "a description of a status code has a status code". You're either describing a status code, which would then be http://example.org/404 a :StatusCode.
and attaching properties to it; or you're describing a status. Looking at the example from the spec:
{
"@context": "http://www.w3.org/ns/hydra/context.jsonld",
"@type": "StatusCodeDescription",
"statusCode": 429,
"title": "Too Many Requests",
"description": "A maximum of 500 requests per hour and user is allowed."
}
we can see that we are describing a hydra:Status
, not a status code. We are saying that there is a status where the user has hit the 500 requests per hour limit, and that this will result in a 429 response.
Hence, I think the correct way would be:
{
"@context": "http://www.w3.org/ns/hydra/context.jsonld",
"@type": "Status",
"statusCode": 429,
"title": "Too Many Requests",
"description": "A maximum of 500 requests per hour and user is allowed."
}
So the message "you hit the limit" is a status, not a code. The property statusCode
can be reused in this scenario.
The other issue is then how to associate such a status with a resource (= the current statusCodes
). I am in favour of using possibleStatus
for this, as this conveys the meaning of what the thing does.
But then I'm unsure about the domain of this property. What can be in this possible status? A single resource? The whole API (= all resources in this API)?
PROPOSAL: Rename "statusCodes" to "possibleStatus" and "StatusCodeDescription" to "Status" and describe that these are enumerations of possible statuses that might be returned at runtime and tell the developer (in prose in hydra:description) how to recover from errors etc. To be clear, "returns" is kept as is and expresses what kind of data can be expected in case of success.
Call for consensus: http://lists.w3.org/Archives/Public/public-hydra/2014Jul/0080.html
RESOLVED: Rename "statusCodes" to "possibleStatus" and "StatusCodeDescription" to "Status"
Should hydra:returns
be moved into a Status
(see http://lists.w3.org/Archives/Public/public-hydra/2014Sep/0089.html)
_Raised by Ruben Verborgh as part of issue #25:_
The case of
statusCodes
shows to how much confusion this leads: we have both astatusCode
and astatusCodes
property.The situation would be that a resource can lead to
statusCodes
X, Y, Z, each of which have astatusCode
200, 400, 500, respectively.I think the correct way is that
statusCodes
becomesstatus
, and that the currentstatusCode
remains the way it is.An alternative would be to rename it to
possibleStatus
oradditionalStatusInformation
.