Introduction

REST API#

Basics#

After You get OpenVPN setup and running You will be able co communicate with Picoides.io Instance.

Instance stands for both master installation for particular project and a gateway depending on Your configuration. Most cases instance would be separated project, like eg. "City of Drones" that would handle multiple gateways and networks spread all over the city...

Access#

Picoides.io runs a web server accessible on port 8123.

  • http://IP_ADDRESS:8123/ is an END USER interface to control Picoides.io.
  • http://IP_ADDRESS:8123/api/ is a Rest API.

The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header X-HA-Access: YOUR_PASSWORD YOUR_PASSWORD as specified in your configuration.yaml file of the picoides.io instance and should be provided on request.

Note

In current version http BASIC AUTH method is used. Refer to standard documentation of solution you use for handling http requests

eg. YOUR_PASSWORD = trafikogobixSadIfIrrwgroakvomDokUshAteahilnimtErchyibeiBlahejAct

Making a request#

There are multiple ways to consume the Picoides.io assistant Rest API. One is with curl:

curl -X GET \
    -u "testuser:YOUR_PASSWORD" \
    -H "Content-Type: application/json" \
    http://IP_ADDRESS:8123/ENDPOINT

Another option is to use Python and the Requests module:

from requests import get
from requests.auth import HTTPBasicAuth

url = 'http://localhost:8123/ENDPOINT'
headers = {'content-type': 'application/json'}

response = get(url, headers=headers, auth=HTTPBasicAuth('testuser', 'YOUR_PASSWORD'))
print(response.text)

Tip

Any standard http client can be used.! Use Your favorit or just best/simplest library dedicated for programming language of your choice...

Response#

Successful calls will return status code 200 or 201 and optionally related data.

Other status codes that can return are:

  • 400 (Bad Request)
  • 401 (Unauthorized)
  • 404 (Not Found)
  • 405 (Method not allowed)

Actions#

Currently the API supports the following actions:

Picoides platform#

Not all entities you'll find on list of states Picoides platform provides it's own set of services and entities states