HTTP Requests

The picosapi module provides wrapper methods for making HTTP requests to Picos. Picos use specifically formatted URLs to make HTTP requests. The picosapi module also provides functions that create these special URL objects for you.

Under the hood, picosapi uses the requests Python module provided by Kenneth Reitz to make the requests (learn more).

GET

The picosapi.get() function makes an HTTP GET request targeting the provided URL endpoint. It takes one required argument and three additional optional arguments:

• purl (required) - a Pico URL (created using either the event_url() or api_url() functions) or a string URL endpoint
• params (optional, default None) - query string parameters to append to the end of the URL, formatted as a dictionary containing {"key": value} pairs.
• headers (optional, default {}) - additional HTTP request headers to send, formatted as a dictionary containing {"header-name": value} pairs
• ok_responses (optional, default [200]) - a list of integers representing acceptable HTTP response codes

This function returns two values: a boolean indicating if the request succeeded (True) or failed (False) and a Response object.

Below is an example of using a GET request with a Pico URL to retrieve information about a person:

import picosapi as picos
...
url = picos.api_url(my_picos_eci, "people_manager", "people")
# This should return a JSON array of people
ok, response = picos.get(url)
if ok:
  name = response.content[0]["name"]
  age = response.content[0]["age"]
  ...
else:
  print(response)
  ...

POST

The picosapi.post() function makes an HTTP POST request targeting the provided URL endpoint. It takes one required argument and three additional optional paramters:

• purl (required) - a Pico URL (created using either the event_url() or api_url() functions) or a string URL endpoint
• data (optional, default {}) - JSON application data to send in the body of the request, formatted as a Python dictionary.
• headers (optional, default {}) - additional HTTP request headers to send, formatted as a dictionary containing {"header-name": value} pairs
• ok_responses (optional, default [200]) - a list of integers representing acceptable HTTP response codes

This function returns two values: a boolean indicating if the request succeeded (True) or failed (False) and a Response object.

Below is an example of using post() to add a new Wovyn temperature sensor to a sensor manager pico:

import picosapi as picos
...
add_sensor_url = picos.event_url(my_pico_eci, "add-sensor", "sensor", "new_sensor")
ok, response = picos.post(add_sensor_url, data={"sensor_id": 24})
if not ok:
  print(response)
  ...

PUT

The picosapi.put() function makes an HTTP PUT request targeting the provided URL endpoint. It takes one required argument and three additional optional paramters:

• purl (required) - a Pico URL (created using either the event_url() or api_url() functions) or a string URL endpoint
• data (optional, default {}) - JSON application data to send in the body of the request, formatted as a Python dictionary.
• headers (optional, default {}) - additional HTTP request headers to send, formatted as a dictionary containing {"header-name": value} pairs
• ok_responses (optional, default [200]) - a list of integers representing acceptable HTTP response codes

This function returns two values: a boolean indicating if the request succeeded (True) or failed (False) and a Response object.

Below is an example of using put() to update temperature sensor profile information for a Wovyn temperature sensor:

import picosapi as picos
...
profile = {
  "name": "Sensor 1",
  "contact": phone_number_string,
  "location": ...
}
update_sensor_url = picos.event_url(my_pico_eci, "update-sensor", 
                                    "sensor", "profile_updated")
ok, response = picos.put(add_sensor_url, data=profile)
if not ok:
  print(response)
  ...

DELETE

The picosapi.delete() function currently is not implemented in picosapi v0.5.2. If called, the function will simply return None.