Wanted: Your thoughts on an upcoming ‘tools’ API

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.

Why not do a hybrid approach?

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.

@mikob, it’s planned that logs will be accessible through the API.

I can’t wait to be able to access the logs from an external website. Any word on when this might roll out?

EDIT: I just saw these two discussion threads. It looks like soon is my answer:



See ‘Testers Wanted

@dheadrick, email your Electric Imp account name to beta AT electricimp.com and we can get you the API key you need. The Build API Beta docs are here.

Is there a way to restart the agent, similar to restarting the device ?

ok, seems like re-assigning the same model does the trick, according to the docs. Let’s test it out…