search

HydraCG / Specifications

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

Clarify how to describe HTTP status #191

Open angelo-v opened 5 years ago

angelo-v commented 5 years ago

Description

Hydra Core Vocabulary has serveral terms / types to express status:

hydra:statusCode hydra:possibleStatus hydra:Status

Unfortunately the spec does not provide usage examples or prose explanation of how to use it and there are serveral (conflicting or obsolete) examples in the wild.

The spec should explain how to use those.

My usage understanding from the vocabulary is:

"possibleStatus": [
  {
    "@type": "Status",
    "statusCode": 201,
    "description": "If the resource was created successfully."
  }
]
alien-mcl commented 5 years ago

Glad we've added some range/domain details. It seems your understanding is OK. There can be a possibleStatus of type Status that can have a property of statusCode. This is to allow de-referencing statuses by the client instead of raw literal.

I'll try to create a proper spec snippet for that

tpluscode commented 5 years ago

What is the practical application other than purely informational?

angelo-v commented 5 years ago

What is the practical application other than purely informational?

Valid questions. Seems to be targeted on human understanding. Don't know what a machine would do with this.

tpluscode commented 5 years ago

I never fully understood this. It has been suggested that it could be (incorrectly) used to generate client code (compare with #32). @RubenVerborgh @lanthaler ?

At any rate, I agree to document this in the current state which everyone has already agreed on.

alien-mcl commented 5 years ago

These kind of constructs makes it easier to prepare some automated tests. Knowing what a operation can return allows you prepare some assertions. Also human readable docs is something we cannot ignore if we think about adoption with big players. When a project begins, one of the first questions from higher managers is 'Where are some docs I can take a look at'?

tpluscode commented 5 years ago

Haha, yes, the manager remark made my day. Human readability should not be neglected either, I agree on that.

But I especially like the idea to put it to use in automatic testing. I do not have a clear idea how exactly it would pan out but it's an intriguing thought.

Any ideas how (rather, where) we could track such ideas? A new repo maybe for a testing tool, or recommendations for testing. Or maybe the cookbook is good enough to document such ideas while we don't have concrete implementation coming?

alien-mcl commented 5 years ago

Any ideas how (rather, where) we could track such ideas? A new repo maybe for a testing tool, or recommendations for testing. Or maybe the cookbook is good enough to document such ideas while we don't have concrete implementation coming?

The cookbook repo sounds interesting. Maybe in future we could have more tools within HydraCG, but i expect them to have separate repos.