This document describes the web API for PumpkinPi.
Returns the collection of all LEDs as JSON.
-
URL
/api/leds
-
Method
GET -
URL Params
None
-
Data Params
None
-
Success Response
Code: 200
Content:[ { "name": "LED 1", "status": "off", "id": "led1" }, { "name": "LED 2", "status": "off", "id": "led2" } ] -
Sample Call
curl -X GET \ http://localhost:5000/api/leds
Returns a single LED as JSON.
-
URL
/api/leds/{id}
-
Method:
GET -
URL Params
Required:
id=[string] -
Data Params
None
-
Success Response
Code: 200
Content:{ "name": "LED 1", "status": "off", "id": "led1" } -
Error Response
Code: 404 Not Found
Content:{"message": "led led3 does not exist"} -
Sample Call
curl -X GET \ http://localhost:5000/api/leds/led1
Sets an LED's status to on or off. Returns a single LED as JSON.
-
URL
/api/leds/{id}
-
Method
PUT -
URL Params
Required:
id=[string] -
Data Params
Required:
{"status": [string]}
Valid status values are "on" or "off" -
Success Response
Code: 200
Content:{ "name": "LED 1", "status": "off", "id": "led1" } -
Error Response
Code: 404 Not Found
Content:{"message": "led led3 does not exist"} -
Sample Call
curl -X PUT \ http://localhost:5000/api/leds/led1 \ -H 'Content-Type: application/json' \ -d '{"status": "on"}'
-
Notes
Since the
statusfield is the only part of the LED object that can be modified, the body of the PUT only requires that field. If other fields are included they will be ignored.
Returns the collection of all sounds that can be played, as JSON.
-
URL
/api/sounds
-
Method
GET -
URL Params
None
-
Data Params
None
-
Success Response
Code: 200
Content:[ { "title": "Hello", "id": "hello.wav" }, { "title": "Happy Halloween!", "id": "happy.wav" } ] -
Sample Call
curl -X GET \ http://localhost:5000/api/sounds
Returns a single sound object as JSON.
-
URL
/api/sounds/{id}
-
Method:
GET -
URL Params
Required:
id=[string] -
Data Params
None
-
Success Response
Code: 200
Content:{ "title": "Hello", "id": "hello.wav" } -
Error Response
Code: 404 Not Found
Content:{ "message": "sound xyz does not exist" } -
Sample Call
curl -X GET \ http://localhost:5000/api/sounds/hello.wav
Plays a sound on the Raspberry Pi speaker.
-
URL
/api/sounds/{id}
-
Method
PUT -
URL Params
Required:
id=[string] -
Data Params
None
-
Success Response
Code: 200
Content:{ "title": "Hello", "id": "hello.wav" } -
Error Response
Code: 404 Not Found
Content:{ "message": "sound zyz does not exist" } -
Sample Call
curl -X PUT \ http://localhost:5000/api/sounds/hello.wav
-
Notes
The PUT method was chosen since the call causes an action to occur on the server (Raspberry Pi). The state of the underlying sound object isn't modified, so no body is required in the PUT. PUTing any existing sound object by id just means "play this sound."
Returns the collection of all features as JSON. Features are capabilities of the PumpkinPi that can be configured.
-
URL
/api/features
-
Method
GET -
URL Params
None
-
Data Params
None
-
Success Response
Code: 200
Content:[ { "enabled": false, "id": "motion-sensor" } ] -
Sample Call
curl -X GET \ http://localhost:5000/api/features
Returns a single feature as JSON.
-
URL
/api/features/{id}
-
Method:
GET -
URL Params
Required:
id=[string] -
Data Params
None
-
Success Response
Code: 200
Content:{ "enabled": false, "id": "motion-sensor" } -
Error Response
Code: 404 Not Found
Content:{ "message": "feature xyz does not exist" } -
Sample Call
curl -X GET \ http://localhost:5000/api/features/motion-sensor
Modifies a feature setting. Returns the modified feature as JSON.
-
URL
/api/features/{id}
-
Method
PUT -
URL Params
Required:
id=[string] -
Data Params
Required:
for id=
motion-sensor
{"enabled": boolean}for id=
webcam
{"brightness": int}
or
{"brightness": "auto-toggle"} -
Success Response
Code: 200
Content:{ "enabled": true, "id": "motion-sensor" } -
Error Response
Code: 404 Not Found
Content:{ "message": "feature xyz does not exist" } -
Sample Call
curl -X PUT \ http://localhost:5000/api/features/motion-sensor \ -H 'Content-Type: application/json' \ -d '{"enabled": true}'
-
Notes
Since the
enabledorbrightnessfield is the only part of the feature object that can be modified, the body of the PUT only requires that field. If other fields are included they will be ignored.For webcam brightness, valid values are 0 through 100 (representing a percentage), or
auto-toggle, which is a special case that toggles the brightness between a high and low value on every capture.auto-toggleis used to work around a problem with certain webcams.
Returns the collection of all photo data as JSON.
-
URL
/api/photos
-
Method
GET -
URL Params
Optional
sortOrder=desc
or
sortOrder=asc -
Data Params
None
-
Success Response
Code: 200
Content:[ { "id": "2018-10-11T14-55-09.415Z.jpg", "path": "/photos/2018-10-11T14-55-09.415Z.jpg" }, { "id": "2018-10-11T14-55-22.171Z.jpg", "path": "/photos/2018-10-11T14-55-22.171Z.jpg" } ] -
Sample Call
curl -X GET \ http://localhost:5000/api/photos
Returns a single photo's data as JSON. If the provided id is "latest", the most recent photo will be returned.
-
URL
/api/photos/{id}
-
Method:
GET -
URL Params
Required:
id=[string] -
Data Params
None
-
Success Response
Code: 200
Content:{ "id": "2018-10-11T14-55-22.171Z.jpg", "path": "/photos/2018-10-11T14-55-22.171Z.jpg" } -
Error Response
Code: 404 Not Found
Content:{ "message": "photo xyz does not exist" }or, when requesting latest:
Code: 404 Not Found
Content:{ "message": "no photos have been captured" } -
Sample Call
curl -X GET \ http://localhost:5000/api/photos/pumpkinpi-2018-10-09-123.jpg
or
curl -X GET \ http://localhost:5000/api/photos/latest
Requests that a photo be captured on the Pumpkin Pi.
-
URL
/api/photos/{id}
-
Method
POST -
URL Params
None
-
Data Params
None
-
Success Response
Code: 200
Content:{ "id": "2018-10-11T14-58-37.065Z.jpg", "path": "/photos/2018-10-11T14-58-37.065Z.jpg" } -
Error Response
Code: 500
Content:{ "message": "unable to capture photo" } -
Sample Call
curl -X POST \ http://localhost:5000/api/photos