Endpoint return values

[ben]

Hi values,

after finishing a few scripts, i wanted to share some feedback.

It seems like you prepared for future endpoint changes, by using /v1/.., right?
So maybe these comments are good enough for a washup in /v2/..

Some functions return "success", some "ok" and some neither one.
I think it would be handy, if all endpoints could return the same status, e.g. "ok", "failed".
That would make it easier to check if the endpoint finished successfully.

Code Select Expand

/v1/authenticate => returns "success"
/v1/categories/assign => returns "ok"
/v1/files/lookup => returns only an array of filenames

Otherwise, really great work!!

Ben

[Mario]

/authenticate is the oldest function. This is probably why it uses "success" and "failed". Too late to change now.

Problem is always how to handle problems, errors, locks, warnings, partial results etc. Returning an HTTP error code, which can only carry the code and a message? Use JSON rich answers for all errors not directly related to the core web service, request processing or parameter checking? Every endpoint can fail for simple (e.g. to many sessions, unauthorized, expired) before iMWS even sees the request. All these are handled via HTTP status codes != 200. And it may fail for complex reasons, later in the processing. Due to locking constraints which will be introduced soon we open up a whole new field of potential endpoint failure (when an app and IMatch try to modify the same object at the same time, only one can win).

I'm not sure still about the best approach. Which is one of the reasons I usually don't document the JSON response and leave that to the programmer. I need some flexibility here over the nexzt months when adding new endpoints for more complex operations. It's hard to write such a vast infrastructure alone. Impossible to get everything right with the first version....

Users who write apps need to be prepared for potential breaking changes, or for me introducing v2/ or v3/ versions of endpoints to ensure backward compatibility without slowing down future developments.