Re: [Specifications] How to document forbidden dereferencability (#216)

> Imagine a situation when API documentation declares a profile A, but inlined controls are using profile B. Which one is in force?

You miss the point. If the API states that it uses profile `A` a client will only expect such controls. Note that this will likely be discovered by humans and not machines.

Now, if such an API in fact uses another profile then a client will likely fail to understand them or it might not care if it supports profile `B` nonetheless.

Again, it's not about precedence. The mention API uses profiles `A` (explicitly) and `B` (implicitly). The client always has to support all of them.

> I think it may be valuable to enable the client to express it's preferences (which then can be taken into account or not - it's up to the server).

Ok, I can see the preference bit now. But I'm not sure about practical usefulness. Would it be something like this?

```
Client: Hey, please given me Resource /XYZ. I understand profiles A and B by te way

Server: Sorry mate. I use profile C for my hypermedia controls
```

So what should happen now? `429 Precondition Failed`?

I actually think of this in an opposite way, where a client retrieves an API Documentation and finds that the API uses certain profiles. It would then load the necessary code to handle them or fail it those profiles are not supported.

This way a client can be modular and not bloated with code not used for a given API.

> I think I can see both terms level and profile used simultaneously - level for spec interpretation, profile for extensibility.

Is it possible that you're overly complicating the proposal? I'd rather that the levels were unnecessary and that the core semantics are uniform.

-- 
GitHub Notification of comment by tpluscode
Please view or discuss this issue at https://github.com/HydraCG/Specifications/issues/216#issuecomment-634937264 using your GitHub account

Received on Wednesday, 27 May 2020 21:01:28 UTC