- From: Sebastien Lambla via GitHub <sysbot+gh@w3.org>
- Date: Mon, 12 Jul 2021 02:46:15 +0000
- To: public-hydra-logs@w3.org
Well, I tend to document all available operations in ApiDocumentation, give them a `@type` of `[Opereation, xxx]` where xxx tends to be a `schema:Action`-derived. I then only enable each operation in a UX if it is in the `operation` property inline in the response for that resource, and add the ones that were not in ApiDocumentation as enabled. It makes sense in that respect. The solution is imperfect, of course, because a lot of customers will look at the static documentation to code their Api, not the inline operation. I do think there's a more generic way that one could annotate operations within a specific context, one that could apply to templates, but as this is for hypermedia clients, I would want to inline some state that would allow a customer to resolve any reason for which this would not be allowed. The two starting points i'd start from is the `Allow` http header that is additive, which tends to be solved by the first approach above, but the second could maybe be generalised with the equivalent of the `enabled` property on html form submit elements. Could we support an `enabled: false` of some kind on `hydra:Operation`, and an additional field describing the current state of the resource? This would have the advantage of taking an external `ApiDocumentation`, say, a standard for banking, and overlaying your own ApiDocumentation on top, or inline an availability, one that could map to an enumeration a la `schema.org`? My thinking would be `availability: Available | NotImplemented | Forbidden | Unauthorized | ConflictsWithCurrentStateOfResource | myapi:DisabledByAdministrator`, maybe making this a class that includes the enabled, and a description that could be useful in rendering user experience? Thinking out loud here, so sorry if the proposal is a bit vague -- GitHub Notification of comment by serialseb Please view or discuss this issue at https://github.com/HydraCG/Specifications/issues/241#issuecomment-877928323 using your GitHub account -- Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config
Received on Monday, 12 July 2021 02:46:20 UTC