mailto:support@algosolutions.com
Home - Algo Communication Products Ltd.
User Guide for ALGO models including: AL061-GU-GF000API-001-R0, AL061-GU-CP00TEAM-001-R0, RESTful API, RESTful, API
Configuration Guides - Algo Communication Products Ltd.
ation - Algo Communication Products Ltd.
File Info : application/pdf, 13 Pages, 303.14KB
DocumentDocumentRESTful API
Guide
For additional support, call (604) 454-3792 or email support@algosolutions.com
AL061-GU-GF000API-001-R0 Firmware Version 5.2 support@algosolutions.com May 29, 2023
Algo Communication Products Ltd. 4500 Beedie Street, Burnaby V5J 5L2, BC, Canada 1-604-454-3790 www.algosolutions.com
RESTful API
Information Notices
Note Note indicates useful updates, information, and instructions that should be followed
Disclaimer
The information contained in this document is believed to be accurate in all respects but is not warranted by Algo. The information is subject to change without notice and should not be construed in any way as a commitment by Algo or any of its affiliates or subsidiaries. Algo and its affiliates and subsidiaries assume no responsibility for any errors or omissions in this document. Revisions of this document or new editions of it may be issued to incorporate such changes. Algo assumes no liability for damages or claims resulting from any use of this manual or such products, software, firmware, and/or hardware. No part of this document can be reproduced or transmitted in any form or by any means electronic or mechanical for any purpose without written permission from Algo. For additional information or technical assistance in North America, please contact Algo's support team:
Algo Technical Support 1-604-454-3792
support@algosolutions.com
©2022 Algo is a registered trademark of Algo Communication Products Ltd. All Rights Reserved. All other trademarks are the property of their respective owners. All specs are subject to change without notice.
AL061-GU-CP00TEAM-001-R0
support@algosolutions.com
Page i
RESTful API
Table of Contents
1 General .............................................................................................................................................................................................1 1.1 Introduction ...............................................................................................................................................................................1 1.2 Authentication ...........................................................................................................................................................................1
2 Setup and Configuration ..................................................................................................................................................................1 2.1 Prerequisites ..............................................................................................................................................................................1 2.2 Enabling the RESTful API ............................................................................................................................................................1 2.3 Enable Basic Authentication (Optional) .....................................................................................................................................2 2.4 No Authentication Method (Optional).......................................................................................................................................2 2.5 Enabling Simple Control Interface (Optional) ............................................................................................................................2
3 Authentication Requirements ..........................................................................................................................................................2 3.1 Standard Authentication Request with a JSON Payload............................................................................................................2 3.2 Standard Authentication Request Without a JSON Payload......................................................................................................4 3.3 Basic Authentication Request ....................................................................................................................................................4
4 Commands........................................................................................................................................................................................6 4.1 RESTful API Commands ..............................................................................................................................................................6 4.2 Simple Control Interface (SCI) Commands...............................................................................................................................10
AL061-GU-CP000API-230529
support@algosolutions.com
Page ii
RESTful API
1 GENERAL
1.1 Introduction
This document describes how Algo RESTful API can be used to access, manipulate, and trigger actions on Algo IP Endpoints on your network through HTTP/HTTPS requests, as well as a couple of different authentication methods with varying levels of security.
Requesting systems can interact with Algo devices through a uniform and predefined set of stateless operations defined in this document. Requests are made to a resource's URI with a JSON payload and elicit a JSON response. HTTP/HTTPS GET, POST, and PUT requests are made to resource URI along with the JSON payload (see commands section for a list of payloads).
1.2 Authentication
There are three types of authentications:
· Standard (recommended) · Basic · None (not recommended) The Standard authentication uses a Hash-based Message Authentication Code (HMAC) with an SHA-256 encoded digest. Basic authentication uses Base64 encoding and should only be used over HTTPS. No authentication should only be used with extreme care as it provides no authentication. See the Authentication Requirements section for more details.
2 SETUP AND CONFIGURATION
2.1 Prerequisites
· This document assumes the Algo endpoint is running firmware version 3.3 or higher. · The time difference between the requestor and the Algo devices should be less than 30 seconds to use standard
authentication. · Ensure NTP (Network Time Protocol) is in use. The addresses of custom NTP servers may be configured in the
Advanced Settings Time tab. Note The pre-configured NTP servers are publicly hosted, therefore internet connection is required to reach it. If no internet connection is available, configure a local NTP server and enter its IP address.
· Ensure the Algo device system time is adjusted to the correct time zone. This can be done by navigating to the Advanced Settings Time tab.
2.2 Enabling the RESTful API
1. Log into the web interface and navigate to the Advanced Settings Admin tab.
AL061-GU-CP000API-230529
support@algosolutions.com
Page 1
RESTful API
2. Scroll down to the API Support section, enable the RESTful API and set the Password as desired (deafault password: algo) Note Standard authentication is enabled by default.
2.3 Enable Basic Authentication (Optional)
1. In the web interface, navigate to the System Maintenance tab and download the configuration file. 2. Open the configuration file with any text editor and add the following line: api.auth.basic = 1 3. Save and upload the modified configuration file back to the device using the Restore Configuration File feature in
the System Maintenance tab.
2.4 No Authentication Method (Optional)
To enable the no authentication method, leave the RESTful API Password field empty. This method is not recommended and should only be used for testing purposes only as it provides no security.
2.5 Enabling Simple Control Interface (Optional)
1. On the web interface, navigate to the System Maintenance tab and download the configuration file. 2. Open the configuration file using a text editor and add two lines. Change the <pw> to your desire password.
Admin.web.sci = 1 Sci.admin.pwd = <pw> 3. Save and upload the modified configuration file back to the device using the Restore Configuration File feature in the System Maintenance tab.
3 AUTHENTICATION REQUIREMENTS
Please email support@algosolutions.com if you would like a standard or basic authentication sample code.
3.1 Standard Authentication Request with a JSON Payload
Required headers in HTTP/HTTPS request > Content-Type: "application/json" > Content-MD5: [content_md5]
Example Content-MD5: 74362cc86588b2b3c5a4491baf80375b
AL061-GU-CP000API-230529
support@algosolutions.com
Page 2
RESTful API
> Authorization: hmac admin:[nonce]:[hmac_output] The authorization headers consist of: 1. The string `hmac admin' followed by a colon `:'. 2. Nonce A random or non-repeating value, followed by a colon `:'. 3. Hmac_output generated by the RESTful API Password (secret-key) configured on your device and the HMAC
input, as per below: [request_method]:[request_uri]:[content_md5]:[content_type]:[timestamp]:[nonce] HMAC input example: (using `algo' as the secret key) POST:/api/controls/tone/start:6e43c05d82f71e77c586e29edb93b129:application/json:1601312252:49936 Generate HMAC with password and HMAC input string as digest using SHA-256: HMAC output example: 2e109d7aeed54a1cb04c6b72b1d854f442cf1ca15eb0af32f2512dd77ab6b330 > Date: day, date month, year hr:min:sec GMT Example Date: Thur, 22 Sept, 2022 02:33:07 GMT Standard authentication with payload example:
AL061-GU-CP000API-230529
support@algosolutions.com
Page 3
3.2 Standard Authentication Request Without a JSON Payload
Identical to 3.1 with content related headers/hmac input omitted. HMAC input: [request_method]:[request_uri]:[timestamp]:[nonce]
HMAC input example: (using `algo' as the secret key) GET:/api/settings/audio.page.vol:1601312252:49936 Generate HMAC with password and HMAC input string using SHA-256:
HMAC output example: c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8 Standard authentication without payload example:
RESTful API
3.3 Basic Authentication Request
This method of authentication should be used with care as it is less secure than the standard method.
AL061-GU-CP000API-230529
support@algosolutions.com
Page 4
> Authorization: Basic [base64]
Example: Authorization: Basic YWRtaW46YWxnbwo= Basic authentication example:
RESTful API
AL061-GU-CP000API-230529
support@algosolutions.com
Page 5
RESTful API
4 COMMANDS
4.1 RESTful API Commands
Below is a list of all supported API commands.
Note A PUT request changes or creates a permanent resource that survives a reboot, while a POST request only controls the device for the current session.
Description
Retrieve the value of a specific parameter.
Return the ambient noise level measured in decibels. Ambient Noise Compensation must be
enabled in Basic Settings -> Features tab.
Method GET
URI
/api/settings/[key-name] Ex./api/settings/audio.page.vol
GET
/api/info/audio.noise.level
Extract the status of the relay input terminal.
GET
/api/info/input.relay.status
Extract the status of Input 1 or Input 2 terminals.
GET
Retrieve the list of tone files currently installed.
GET
Retrieve the device information
that is displayed on the Status
GET
page.
/api/info/input.relay1.status or
/api/info/input.relay2.status
/api/info/tonelist
/api/info/status
Payload Parameters N/A N/A
N/A N/A N/A N/A
Return Example {"audio.page.vol": "-18dB"}
Product
FW
All
> 3.3
{"audio.noise.level": 72}
Speakers > 3.3
Display Speakers
{"input.relay.status": "idle"} or
{"input.relay.status": "active"}
All products with a
relay input, except the 8063. See
> 4.1
below.
{"input.relay1.status": "idle"}
or
8063
> 4.1
{"input.relay1.status": "active"}
{"tonelist":["bell-na.wav","belluk.wav","buzzer.wav",...]}
All
> 5.0
Full list of information from the Status tab.
All
> 5.4
AL061-GU-CP000API-230529
support@algosolutions.com
Page 6
RESTful API
Description
Method
Retrieve the product information
that is displayed on the About
GET
page.
Activate the strobe with desired color and pattern parameters.
POST
URI /api/info/about
/api/controls/strobe/start
Payload Parameters
Return Example
N/A
All information present on the About tab.
pattern: {0 - 15}
color1: {blue, red, amber, green}
color2: {blue, red, amber, green}
N/A
ledlvl: {1 - 255}
holdover: {true, false}
Stop the strobe.
POST
/api/controls/strobe/stop
N/A
N/A
path: {tone}
ie. chime.wav
Play a tone once or loop it.
POST
/api/controls/tone/start
loop: {true, false} or {0, 1}
N/A
e.g. {"path":"chime.wav", "loop":true}
Stop the tone.
POST
/api/controls/tone/stop
N/A
N/A
Call a phone extension with a prerecorded message.
POST
/api/controls/call/start
{"extension":"2099", "tone":"gong.wav", "interval":"0", "maxdur":"10"}
N/A
End the call.
POST
/api/controls/call/stop
N/A
N/A
Product
FW
All
> 5.4
8128(G2)
8138
> 3.3
8190S
8128(G2)
8138
> 3.3
8190S
Speakers
8301
8373 8028(G2)
> 3.3
8201
8039
Speakers
8301
8373 8028(G2)
> 3.3
8201
8039
Speakers
8301 8410
> 3.3
8420
Speakers
8301 8410
> 3.3
8420
AL061-GU-CP000API-230529
support@algosolutions.com
Page 7
RESTful API
Description
Initiate a one-way page call. The device will receive the audio stream from target extension.
Reboot the target endpoint.
Unlock the door. "local" controls the local relay "netdc1" controls the remote network door controller (8063)
Method POST POST POST
URI /api/controls/call/page /api/controls/reboot /api/controls/door/unlock
Lock the door.
POST
/api/controls/door/lock
Enable the 24v aux out relay. Disable the 24v aux out relay.
Enable the output relay. Disable the output relay.
Check Algo's firmware server for latest firmware version.
POST POST POST POST
POST
api/controls/24v/enable api/controls/24v/disable /api/controls/relay/enable /api/controls/relay/disable
/api/controls/upgrade/check
Check Algo's firmware server for latest firmware version and
upgrade to that version.
POST
/api/controls/upgrade/start
Display an image or pattern on the screen.
Stop the screen pattern and return to the default screen.
POST POST
/api/controls/screen/start /api/controls/screen/stop
Payload Parameters {"extension":"<ext>"}
N/A doorid: {local, netdc1}
*Optional
doorid: {local, netdc1} *Optional N/A N/A N/A N/A N/A
N/A
See below N/A
Return Example
N/A
N/A
N/A
N/A
N/A N/A N/A N/A {"version": "updated"} or {"version": "<fw version>"} {"status": "updated"} or {"status": "upgrading <fw version>", "url": <download url>} or {"status": "<message>"}
N/A
N/A
Product Speakers
8410 8420
All 8039 8028(G2) 8201 8063 8039 8028(G2) 8201 8063 8063 8063 8063 8063
All
All
8410 8420 8410 8420
FW > 5.3.4 > 3.3 > 3.3
> 3.3 > 5.0 > 5.0 > 5.0 > 5.0 > 4.1
> 4.1
> 5.3.4 > 5.3.4
AL061-GU-CP000API-230529
support@algosolutions.com
Page 8
Description
Restart the main application.
Start listening to a direct audio stream. Configure the port
number to which the stream is being sent.
Stop listening to a direct audio stream.
Method POST POST
POST
Set the multicast mode.
PUT
URI /api/controls/reload /api/controls/rx/start /api/controls/rx/stop
/api/state/mcast/update/
Payload Parameters
N/A
{"port": <port>}
N/A
{"mode":"sender", "address":<address>, "port":<port>, "type":"rtp"}
or {"mode":"sender", "address":<address>, "port":<port>, "type":"poly",
"group":1}
**Note**: If controls/tone/start is used before this command, the tone will play using current settings on the web UI.
Insert a value to a specific parameter from JSON payload.
PUT
/api/settings
parameter: {value} e.g. {"audio.page.vol": "-3dB"}
Return Example N/A N/A N/A
N/A
N/A
RESTful API
Product All
All
FW > 5.3.4
> 5.3.4
All
> 5.3.4
8301
> 5.0
8180(G2)
8186
8190 8190S
> 3.3
8301
8373
AL061-GU-CP000API-230529
support@algosolutions.com
Page 9
RESTful API
4.2 Simple Control Interface (SCI) Commands
All SCI commands are GET requests and have the common parameters "usi" and "admin" for authentication.
Example: GET http://<IP>/sci/controls/door/unlock?usr=admin&pwd=algo&doorid=local
Description
URI
Unlock the door.
"local" controls the local relay "netdc1" controls the remote network door
controller (8063)
/sci/controls/do or/unlock
Additional Payload Parameters
doorid: {local, netdc1} *Optional
Lock the door.
/sci/controls/do or/lock
doorid: {local, netdc1} *Optional
Play a tone once or loop it. Stop the tone.
Activate the strobe with desired color and pattern parameters.
/sci/controls/to ne/start
/sci/controls/to ne/stop
/sci/controls/str obe/start
path: {tone} ie. chime.wav loop: {true, false} or {0, 1}
N/A
pattern: {0 - 15} color1: {blue, red, amber,
green} color2: {blue, red, amber,
green} ledlvl: {1 - 255} holdover: {true, false}
Stop the strobe.
/sci/controls/str obe/stop
N/A
Products FW
8039
8028(G2) 8201
> 3.3
8063
8039
8028(G2) 8201
> 3.3
8063
All
> 3.3
All
> 3.3
8128(G2)
8138
> 3.3
8190S
8128(G2)
8138
> 3.3
8190S
AL061-GU-CP000API-230529
support@algosolutions.com
Page 10