REST API
qbee.io has a REST API that allows to access all functionality that is available in the frontend UI. This also includes the key-value pairs that are used in templating. A full REST API description can be found following the link. For your convenience and to enable simple testing a sandbox option is available for testing API calls.
This tutorial has four parts:
- How to create an API user?
- How to use the API sandbox without 2FA?
- How to use the API sandbox with 2FA enabled?
- How to do REST API calls from a script or an application?
How to create an API user?¶
As a first thing you need to create an API user. We recommend to use an API user without 2-factor authentication enabled. Below you will see how you can override a general 2FA policy for the API user. It is possible to use the sandbox and the API from your software with 2FA. But then the procedure gets slightly more complex as described in the sandbox with 2FA part.
How to create an API user?
We recommend to have 2FA enabled, but not for the API user. Here is how to override 2FA for this user:
How to use the API sandbox without 2FA?¶
On the API page there is a sandbox option that allows to easily extract json information when logged in. This is often used to test and optimize queries. This is a two step process in which a token needs to be queried and then this can be used:
Sandbox without 2FA
-
Login
Locate: /api/v2/login from here.
Click on sandbox tab and enter your username and password then click try.
On successful login you’ll get a reply with the token. Copy the value of token
-
Do the API call you want, for example, get device tree
Locate: /api/v2/grouptree from here.
Click on the sandbox tab
Enter the following into the Headers:
Key => authorization
Value => Bearer <token from the login step>
Click on
Try!You should get the device tree
How to use the API sandbox with 2FA enabled?¶
It is fully possible to use the REST-API with 2FA enabled:
Sandbox with 2FA enabled
- Do step 1 from above and copy the value of the “challenge”
-
Find the authentication section and open the /api/v2/challenge-get section.
Enter the copied challenge into the challenge field.
Enter email or google (depends on what is available for you) into the “preferProvider” field.
-
Click
Try! -
You will get a response, copy the value of the “challenge” and check your email for the code
-
Find the /challenge-verify section
-
Enter copied challenge from step 4 into the challenge field and code from email into the code field
-
Click
Try! - As a response, you’ll get the token, which you should use in the same way as in step 2 from the non-2fa section
How to do REST API calls from a script or an application?¶
The same mechanism that works in the sandbox can also be implemented in code. Below we give you some bash examples but this can be implemented in any programming language. In these examples we assume that the API user has no 2-factor authentication enabled. This is for simplicity. You can of course also tweak this to use 2FA as described in the sandbox example.
The authentication is jwt based. Therefore you need to install the jq package or something similar:
Install jq
apt-get install jq
The following example script shows how to authenticate and get the grouptree information. Username and password are provided as system variables $QBEE_USER and $QBEE_PW.
grouptree_no_files.sh
successful_status_code='200'
auth='false'
i=0
token=""
while [[ "$auth" != "true" && $i -lt 10 ]]
do
echo "try number $((i++))"
output=$(curl --request POST -sL --url 'https://www.app.qbee.io/api/v2/login' \
--header "Content-Type: application/json" \
-d "{\"email\":\"$QBEE_USER\",\"password\":\"$QBEE_PW\"}"\
-w "\n{\"http_code\":%{http_code}}\n")
http_code=$(echo $output | jq -cs | jq -r '.[1].http_code')
echo $http_code
tokenValue=$(echo $output | jq -cs | jq -r '.[0].token')
echo $tokenValue
if [ "$http_code" != "$successful_status_code" ]
then
echo $tokenValue
#uncomment next line to do nothing
#:
else
auth='true'
apiOutput=$(curl --request GET -sL \
--url 'https://www.app.qbee.io/api/v2/grouptree?_format=json'\
--header 'Authorization: Bearer '"$tokenValue")
echo "API output is:\n$apiOutput"
#uncomment to following to write to a file instead:
# curl --request GET -sL \
# --url 'https://www.app.qbee.io/api/v2/grouptree?_format=json'\
# --output './grouptree_result.json' \
# --header 'Authorization: Bearer '"$tokenValue" \
# echo "$(cat grouptree_result.json)"
fi
done
Based on the above authentication a file delete and file upload would look like this:
delete_and_upload_file.sh
successful_status_code='200'
auth='false'
i=0
token=""
while [[ "$auth" != "true" && $i -lt 10 ]]
do
echo "try number $((i++))"
output=$(curl --request POST -sL --url 'https://www.app.qbee.io/api/v2/login' \
--header "Content-Type: application/json" \
-d "{\"email\":\"$QBEE_USER\",\"password\":\"$QBEE_PW\"}"\
-w "\n{\"http_code\":%{http_code}}\n")
http_code=$(echo $output | jq -cs | jq -r '.[1].http_code')
echo $http_code
tokenValue=$(echo $output | jq -cs | jq -r '.[0].token')
echo $tokenValue
if [ "$http_code" != "$successful_status_code" ]
then
echo $tokenValue
#uncomment next line to do nothing
#:
else
auth='true'
apiOutput=$(curl -i --request "DELETE" -d "path=/my-folder/my-file.txt" -H "Content-type: application/x-www-form-urlencoded" \
--url 'https://www.app.qbee.io/api/v2/file'\
--header 'Authorization: Bearer '"$tokenValue")
echo "API output is:\n$apiOutput"
apiOutput=$(curl -i --request POST -H "Content-Type:multipart/form-data" -F "path=/my-folder/" -F "file=@my-file.txt" \
--url 'https://www.app.qbee.io/api/v2/file'\
--header 'Authorization: Bearer '"$tokenValue")
echo "API output is:\n$apiOutput"
fi
done
In some of our demos we use GitHub runner actions do distribute Node-RED files. This is basically a simple CI/CD (continuous integration / continuous deployment) pipeline. An example can be found here. Below you see how such a GitHub runner action would look like assuming your GitHub secret for user is "QM" and for password is "QP":
main.yml
name: Automated Node-RED flow file distribution
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
env:
TARNAME: node-red-files.tar
steps:
- uses: actions/checkout@v2
- name: create tarball
run: |
mkdir ./tar
tar --exclude='./.git' --exclude='README.md' --exclude='./.github' --exclude='./tar' -czvf ./tar/$TARNAME .
- name: install jq
run: |
sudo apt-get install jq
- name: copy to qbee file manager with jwt authentication
run: |
successful_status_code='200'
auth='false'
i=0
token=""
while [[ "$auth" != "true" && $i -lt 10 ]]
do
echo "try number $((i++))"
output=$(curl --request POST -sL --url 'https://www.app.qbee.io/api/v2/login' \
--header "Content-Type: application/json" \
-d "{\"email\":\"${{ secrets.QM }}\",\"password\":\"${{ secrets.QP }}\"}"\
-w "\n{\"http_code\":%{http_code}}\n")
http_code=$(echo $output | jq -cs | jq -r '.[1].http_code')
echo $http_code
tokenValue=$(echo $output | jq -cs | jq -r '.[0].token')
echo $tokenValue
if [ "$http_code" != "$successful_status_code" ]
then
echo $tokenValue
#uncomment next line to do nothing
#:
else
auth='true'
apiOutput=$(curl -i --request "DELETE" -d "path=/node-red-demo/$TARNAME" -H "Content-type: application/x-www-form-urlencoded" \
--url 'https://www.app.qbee.io/api/v2/file'\
--header 'Authorization: Bearer '"$tokenValue")
echo "API output is:\n$apiOutput"
apiOutput=$(curl -i --request POST -H "Content-Type:multipart/form-data" -F "path=/node-red-demo/" -F "file=@./tar/$TARNAME" \
--url 'https://www.app.qbee.io/api/v2/file'\
--header 'Authorization: Bearer '"$tokenValue")
echo "API output is:\n$apiOutput"
fi
done
Please let us know if you have any questions. We can help you to get started with the API. And please remember that you can also control location and much more with the API.