Update spec: return errors as Objects – (and a 'Not Implemented' code?)

[bblodfon]

Not all real-world APIs support some of the operations requested by getDictInfos or getEntries for example.
Usually this issue had to do with asking more general information from the APIs - e.g. asking for all dictionary information, all entries (in all possible sub-dictionaries/ontologies).

Thus, the specification should include information on what object should these functions return in these cases.

E.g., it could be something like:

{
  status: 400,
  error: 'Not implemented'
}

[bblodfon]

404 as status is better, as it stands for "Not Found"

[bblodfon]

error: 'Not supported' is also better

[stcruy]

Yes, the spec would benefit if that were written into it:

• on error: always return an Object with at least an error property.
• on error: a status property could be added too. But for now I'd leave it up to each particular ‘vsm-dictionary-xyz’ implementation to specify what that status mean in their case – since this seems to reflect a HTTP error code that is returned by the server of the particular API, addressed by that vsm-dictionary.
• and add that some functionality (like getting all dictInfos, etc) may not be supported by some APIs. Which means that code that depends on a vsm-dictionary should deal with errors gracefully, and show some flexibility in getting data (e.g. if the user can not query them all, the software should not crash or freeze, but instead enable the user to query them by name).

I'm not convinced we need to require the use particular error Strings. Because that would mean that we take a responsibility to define many more possible error codes, over time. But we have no use-case for it (i.e. to make it machine-interpretable).

I think that modules that call a vsm-dictionary's code simply have to account for the fact that a truthy err means that the data is unavailable, for whatever reason, and they have to deal with that.
The err.error would only server as information to the user. And the Object form would prepare for extensions for real use-cases in the future.

• ➝ So: the bullet points on top are to-dos.
• But this then also needs 'vsm-dictionary-local' (and perhaps more) to be updated accordingly, soon after.