Electric Imp is currently developing a new API that will allow developers to access our device and agent code provisioning system without having to go through the IDE.
For example, the API will allow toolmakers to integrate functionality that will allow those tools’ users to get a list of current development devices, a list of models, and get not only the latest versions of the device and agent code that make up those models but also earlier versions. New code can be uploaded to existing models, or to a new model created via the API. Devices can be reassigned to different models, or restarted.
Whatever you can do in the IDE, you’ll be able to do through your own tools.
All of the operations which the API makes possible will generate a response indicating whether the operation was successful or failed. In the case of failure, the response indicates the nature of that failure. The question is, what should those responses be?
We think there are two possibilities:
An extensive list of HTTP status codes covering all possible failures, whether due to incorrect use of the API (using an API method the wrong way), incorrect data passed to the API (passing the name of a non-existent device, say), authorization failure (incorrect username or password) or service issues (the API server is being maintained).
A simplified response code list, each of which is accompanied by a human readable description within the body of the response.
Both approaches have their pros and cons, so we’d like to hear from you, the developers, which of these approaches – or something else – would you find most helpful? Let us know your thoughts below.
Perhaps a limited number of HTTP status codes (maybe one from each 100 domain) so a developer can do a relatively simple check to see if there was an error and the category of error that occurred.
For more granular error handling, a JSON response could be provided that includes a few guaranteed fields - namely a numeric Error Code, an enumerated Error String, and the human readable error description. Add additional, optional keys for any other pertinent error information.
Keeps things simple while leaving lots of flexibility and power in developers’ hands that want it.
Obviously, a command line wrapper for the library is a must. One other thing I’ve seen (although to be fair I’ve not played with so it may not be so great) is Spark Dev which looks to be a fork of the Atom open source editor (which I have used and am a fan of) - http://docs.spark.io/dev/. Maybe something else worth looking into…
As the API will likely be used from a custom made environment, the adherence to standard http status codes isn’t that important in my view. What is important is that the human readable error indication leaves no room for interpretation.
Would the API also allow to do code syntax checking, including providing direct feedback on where teh errors are (which line(s)) ?
@vedecoid I’m sure it will, as the already existing POST when you do a build & run returns syntax error descriptions along with a line number.
I agree with @deldrid1, where in some cases an http error code would be appropriate, other cases a 200 should be returned along with a human readable error code/string (ie. syntax errors).
I think most developers will still want to have the ide open, most importantly to see logs. Unless logs will be integrated in the API? Will the web IDE be made realtime – such that when I push code through the API, the build number and code changes will update without a page refresh? It’s less important for the web IDE to be realtime, if logs can be obtained via this new API.
@vedecoid, the API talks to our backend system, which handles syntax checking. Syntax errors would be reported back (if they exist) when you upload your code, in response to the upload.