Using the REST api

Introduction

The REST api provides access to controls through the use of Web calls. You can use simple web calls.

The REST README provides some deeper information on the different types of endpoints, but this will get you started.

For the purpose of this tutorial, we’ll start with a simple Project to fill a 50 pixel RGB light strip with solid blue.

shape: 50
animation:
  typename: fill.Fill
  palette: blue

Starting BiblioPixel with the REST API enabled

In order to start the rest api, we must add just two lines of YAML. We are assuming that you are running this one the same computer as your browser. If not, we’ll address that in the next section.

shape: 50
animation:
  typename: fill.Fill
  palette: blue
controls:
  typename: rest

You rest API gets setup on port 8787 of your localhost by default. It is not externally accessible as there are no authentication methods in place.

You should now be able to go to http://127.0.0.1:8787 and see a very simple form to build some basic API requests. Try putting animation.palette into the Address box and hitting the Get button. You should have the RGB values for blue returned.

Make your API remotely accessible

To make this remotely accessible, you will need to add external_access: true to the controls section like this.

controls:
  typername: rest
  external_access: true

Now you should be able to access the same API with http://YOURIP:8787. Replace YOURIP with your computer’s IP. If you have problems, consider your computers firewall may be blocking external access on port 8787.

Changing the port

If you wish to change the port of the API server, you can do so with something like this.

controls:
  typername: rest
  external_access: true
  port: 8888