API Error Reporting Consistency


#1

In working with Exosite’s APIs, I’ve found a number of consistency issues I would wish to see addressed.

Here is an example of a Postman session with the whitelisting API (documented here: http://docs.exosite.com/tutorials/provisioning/):

In the first screenshot, I am using an expired token. In the second, I am trying to whitelist a device that has already been whitelisted.

The main issue I want to draw your attention to here is that errors are not reported in a consistent format. This makes it essentially impossible to handle errors reliably. I can notice I have received an error and try to deserialize the response to determine what the error is, but maybe the error is reported in some surprising new format, and I’ll just have an error reading the error.

As a developer who wants a good user experience for my application, this means many more hours debugging Exosite errors, and increased complexity in handling various failure scenarios gracefully.

I’m hopeful you’ll recognize this as an issue and will be willing to take steps to improve consistency in your APIs. Thanks for your attention!


#2

@atp

Thanks for bringing this to our attention. I will make the Development team aware of this, so they can be sure to include the device2 in the other consistency efforts they are making.

However looking at the host you are calling, you are not using the HTTP Device API. You appear to be calling the device2 microservice gateway directly. This is not the expected way to provision devices on Murano and this interface isn’t meant to be used directly. Is there some automated device provisioning task you are trying to accomplish that you were unable to do with the standard interface? Are you trying to provision devices through a Murano Application Solution?

I recognize the larger issue, but this usage strikes me as odd.

Happy to help,
-Martin


#3

@atp,

My Product Manager @rbkucera pointed out to me that we have that host and those endpoints documented as the whitelist API on our docs site. I was concerned that these message were routing to the microservice directly, but I understood the configuration incorrectly. This is a separate interface set up for the purpose of automatically whitelisting devices individually or in bulk.

This is the proper way to whitelist devices using 3rd party applications.

I’ll talk to our development team to see what we can do to bring this section of the API in line with our other interfaces

Hopefully this helps,
-Martin