LIFX Developer Zone

HTTP API Changes - v1beta1 - 2015-08-28


#1

We’ve made some changes to v1beta1:

  • Added PUT /lights/[selector]/state - change state of lights within selector
    • Takes the following parameters (all optional):
      • power - on or off
      • color - colour specifier
      • brightness - 0.0 - 1.0, overrides any brightness set in color (if any)
      • duration - seconds, 0.0 - 3155760000.0 (100 years~), defaults to 1.0
  • Deprecate PUT /lights/[selector]/color and PUT /lights/[selector]/power in favour of the above. These will be removed in 1.0
  • Added PUT /lights/states - change states of multiple selectors
    • Takes the following parameters:
      • states - required, array of hashes the following fields:
        • selector - light selector, required
        • power - on or off, optional
        • color - colour specifier, optional
        • brightness - 0.0 - 1.0, overrides any brightness set in color (if any), optional
        • duration - seconds, 0.0 - 3155760000.0, optional, defaults to 1.0
      • defaults - optional, hash with the fields:
        • power - on or off, optional
        • color - colour specifier, optional
        • brightness - 0.0 - 1.0, overrides any brightness set in color (if any), optional
        • duration - seconds, 0.0 - 3155760000.0, optional, defaults to 1.0
    • If defaults is supplied, each hash in states will be merged from defaults
    • Returns an array of hashes:
      • operation - hash of the operation that was performed, including defaults and selector
      • results - what you would normally get if you hit PUT /lights/[selector]/state:
        • id - id of the light
        • label - label of the light
        • status - ok, timed_out or offline

We’re open to feedback to these changes, and will be holding off adding these to the documentation for a week as we gather feedback from the community. Please let us know if the API does not function as expected, or is failing to meet a particular use case.


Using Scenes in the API
#2

Looks good to me from first glance, certainly using state rather than power and color is a very good move.


#3

List lights appears to be broken - in fact everything seems to be returning a 404 at present.


#4

I’m the on-call technician this week. I’m looking into it now. Initially it seems to just be a documentation issue, as other integrations seem to all be working. I’ll follow up in a few minutes…


#5

Okay I made a change to the version string in readme.io in order to accommodate the future v1 release of the API which we are currently preparing for. I thought this change would only affect the v1 documentation but it seems the setting is project wide. This means when I changed the version string it also affected the documentation for the currently released version and broke all the released documentation.

I’ve reverted the change and tested that the API documentation now works as expected.

Thanks for catching this and reporting it to us. We wouldn’t have caught it until Monday morning otherwise.


#6

Oops - I probably should have checked more than just the documentation - my bad. But still, I suppose I was of some use.


#7

Just to clarify using this new call, omitting power is the intended equivalent to providing power_on=false to the deprecated set_color api call, yeah?


#8

If the target is already off and you omit the power parameter then it would be equivalent.


#9

Awesome, thanks!

[making up 20 chars for the silly limit]


#10

@lparry Generally it is better to use the like button if all you want to do is say thanks. That’s why we have the post limit. :smiley:


#11

The HTTP documentation is wrong isn’t it ?

This is your sample.
-d “state=on” “https://api.lifx.com/v1beta1/lights/all/power

it should be -d “power=on” “https://api.lifx.com/v1beta1/lights/all/state


#12

I’ve fixed this, thanks for letting us know!