HydraCG/Specifications

Clarify how to describe HTTP status

angelo-v opened this issue · 7 comments

angelo-v commented

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

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

What is the practical application other than purely informational?

angelo-v commented

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

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

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

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

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.