This API is still being under development but this page will outline each of the API methods currently available available.

The Energenie API is created using the Moonrope specification. The following document explains how to make requests and how responses are formed.

• All requests are made using HTTP.
• All responses will be returned in JSON.
• The HTTP verb doesn't matter but POST is recommended.
• Authentication information is provided using HTTP Basic auth.
• HTTP status codes can be ignored as the status is provided in the standard JSON response. Most requests will return a 200 OK with the exception of a 500 Internal Server Error.

The API implements a number of actions which are split into controllers. The documentation is split into the same hierarchy and each controller has it's own section and each action has its own page.

URL

API requests should be made to the following URL and replacing controller & action with the appropriate values for your request.

https://mihome4u.co.uk/api/v1/controller/action

User Agent

A User-Agent header is recommended but not required. Including such a header will help us help you when debugging any issues you might have when making API requests.

API Limits

API access is currently unrestricted however limits will be imposed in the future.

Parameters

To send parameters to an API action, you must encode them in a JSON hash and send them in the params HTTP parameter. For example, your HTTP body might look like this:

params={"key":"value"}

Authentication

Users may authenticate using HTTP Basic authentication. The username will be the user's email address. The password may be the user's normal password (as used for the web interface) or the user's API key (fetched using the Profile API call). It is recommended to use a password only to retrieve an API key, then store an use the API key for further requests.

All requests must be authenticated with the exception of user registration.

Responses

All responses from the API will be returned as JSON. You can verify the content type using the HTTP Content-Type header. For JSON responses, this will be application/json.

Every request will include a JSON payload similar to this one:

{
  "status":"success",
  "time":1.3,
  "flags":{},
  "data":"..."
}

The status attribute includes the status of the request and can be one of the following values:

• success - the request was successfully performed
• not-found - a resource which was requested could not be found
• access-denied - access to the requested action was not permitted
• parameter-error - the parameters provided were not suitable for this action
• validation-error - a resource could not be created/updated/removed due to a validation error. This is usually accompanied by errors in the data attribute.
• maintenance - the API is currently unavailable for maintenance work.
• internal-server-error - an error outside of your control occurred. Please report these to the team if they persist.

The time attribute specifies how long the request took to perform on the server. This doesn't include any time spent sending or receiving the HTTP request.

The flags attribute includes extra information for your request. For example, if data is paginated you'll find a pagination flag which will include information about the number of pages and the records returned.

The data attribute contains the actual response. This can be a hash, array , string, integer or just a boolean (true/false) value.