search

w3c / wot-discovery

Repository for WoT discovery discussion
https://w3c.github.io/wot-discovery/
Other
20 stars 17 forks source link

Issues with format listing option in TDD API #539

Open egekorkan opened 10 months ago

egekorkan commented 10 months ago

Coming from a discussion with @relu91.

The text at https://w3c.github.io/wot-discovery/#directory-api-spec says:

To tell the server which format to send, the additional query parameter ?format=array|collection can be added to the request. ?format=array is the default parameter, does not have to be provided explicitly, and yields to a server response of the pure array of TDs. ?format=collection should yield to a server response with the format as described in Example 9. The listing operation is specified as things property in 7.3.2.4 API Specification (Thing Model).

First of all, this is not marked as an assertion. Implementations can miss this.

Secondly, it is not clear how to mention you don't support collection or array within format. According to the TM, all TDDs need to support both but if the Discoverer doesn't provide format, you can use a default term. This is an overall limitation on using TM to specify a flexible specification. If the TD of TDD does not provide one value, it is a wrong implementation since a TD cannot remove parts of a TM.

mmccool commented 8 months ago

The issue with not being able to mention optional features in a TM is something that I think needs to be fixed in the TM spec, if possible. If/when it is, we can resolve the second point by updating the TDD's TM appropriately. Otherwise we will probably have to go in the other direction and not constrain/mention optional features at all. I don't think that's a great solution, it means the TM description of the API would be incomplete (although particular TDDs could add stuff to their own TDs). Maybe optional mixin TMs? Ugh.

As to whether or not this should be an assertion, in some cases we took out assertions (or turned them into explanatory text) if they were duplicates e.g. of a table assertion. I'm not saying that's the case here but we will have to check.

farshidtz commented 8 months ago

There is an assertion for this, a few paragraphs above:

As an alternative to an array of TDs as the body of the response, the server MAY send a more verbose payload allowing server-side information, such as pagination information, to be included in addition to the actual data.

So, the collection format is optional.

As for the error message, the server should respond with a 400 or 501. See the following assertion:

When a directory is unable to answer a request because of unsupported recommended or optional features, it SHOULD inform the client about the absence of those features by returning appropriate HTTP errors.

And the examples that follow:

  • If the missing feature is to customize functionality of an existing API use 400 (Bad Request) or 501 (Not Implemented).
  • If an API endpoint is not provided (e.g. /search/sparql endpoint), use 404 (Not Found).
  • If a method is not supported on an existing API endpoint (e.g. PATCH for /things endpoint), use 405 (Method Not Allowed).

https://www.w3.org/TR/wot-discovery/#exploration-directory-api