User Guide | My Utility Genius API

Obtain guideance on the way and best approach to take full advantage of our full suite of APIs. For detailed documentation and usage examples, you may see our documentation. If you have any question please do not hesitate to contact us.



Registration


You need to be registered for our services before you may make use of any of our APIs. During registratin you need to:


The registration MUST be approved before you can use the services.



API Requests


For security, request are required to be made over the TLS protocol.

    https://api.myutilitygenius.co.uk/{yourRequest}

Although other MIME types may be used, "application/Json" is the official MIME type supported

    Accept: application/json

All request URI's should not exceed 260 characters in length. On making a request you should state the version of the API that you require. If the version is not stated it would be presumed that the default one is required. You explicitly state the version of the API that you require in the accept header like so:

    Accept: application/json; version=default

In the above example a request was made on the “default” version of the API for a MIME type of "application/json" response.


Depending on the request made (typically POST) some requirements in the body are grouped as a BindingModel. BindingModels are simple JSON objects conveniently grouped together for management and readability. As an example, a PersonBindingModel is shown below:

    PersonBindingModel: [
        {
            firstName="Some",
            middleName="Random",
            lastName="Name"
        }  
    ]

In the example above, the PersonBindingModel is a JSON object describing a person whose keys state values for a first, middle, and last name.



API Responses


All API always responds with a status code response. These status codes are chosen to give as much useful information about the request made as possible. If there is a response body it would typically be a Response that consists of one or more of the following:



Making Requests


Once registered is complete - i.e. your request origin (or host address) is approved - you would be able to request an authorisation Token. An authorisation token needs to accompany every request made.

You request an authorisation token by making a POST request at the token endpoint:

    https://api.myutilitygenius.co.uk/request/MyUtilityGeniusApiToken 

In the header of the request, you would need to state a form encoded content-type.

    Content-Type: application/x-www-form-urlencoded

In the body of the request, you would need to state your username and password created during registration, and a grant_type of password in a serialized form:

    grant_type=password&username={YourUsernameFromRegistration}&password={YourPasswordFromRegistration}   

If the request is succesful (and in turn authenticated) you can expect to get a JSON formated response. The sample shown below is similar to what you can expect:

    {
        "access_token":"d96tM0nCKx2G1Gz[...]", // this has been shortened for conciseness
        "token_type":"bearer",
        "expires_in":86399,
        "userName":"YourUsernameFromRegistration",
        ".issued":"Mon, 01 Jan 2014 08:01:25 GMT",
        ".expires":"Mon, 02 Jan 2014 08:01:25 GMT"
    }

The access_token (defined by the token_type) is required when making every request. In the above example the token "d96tM0nCKx2G1Gz[...]" is of type "bearer"" and is valid for 24 hours. Within that time you can make as many request (as allowed by your registration). After 24 hours you would need a new bearer token to make additional requests to the API.


To make a request, simply include an Authorization header denoting a bearer type together with the bearer token.

    Authorization: Bearer d96tM0nCKx2G1Gz[...] 

The token sample above has been shortened for conciseness.


Client request to the token endpoint authenticates the them. However it's the token that authorizes the client for access to protected resources.

You can make as many request as you like to obtain multiple tokens each of which would be valid for the time stated.

The API is a completely cookieless service and in turn adds to its already secure design.



General




API service list


Can be found here