How To Get Started With Biostar 2 Api: Compiled by George Cartlidge

How to get started with
BioStar 2 API
Compiled by
George Cartlidge
What is the API or SDK, and what is the difference?
API stands for Application Programming Interface, where SDK stands
for Software Development Kit.
An API is a set of functions that allows you to interface with an

existing bit of software (I.E BioStar 2), This means any interaction
with Suprema devices will need an installation of BioStar 2 to be
already installed and that you are actually interacting with the
BioStar 2 server and not the devices. Starting with BioStar 2.7.10,
there is a new version of the API that includes more functions.
An SDK is a collection of tools that you can use to develop your own
applications using a particular framework/platform. Regarding the
BioStar 2 SDK, this will be the BS_SDK_V2.dll file. This .DLL contains
many APIs that can be used with C++ & C# programming languages.
There is also the new G-SDK which functions along the same principal
but is based upon gRPC which can support more languages that the
existing SDK. Using the SDK, you cut BioStar 2 out completely and
directly interact with the device.
Comparing both, the API will be used where you are happy for
BioStar 2 to handle most of the work, BioStar 2 would be storing the
fingerprint and user data; The API lets you use BioStar 2 from inside
another application, so it does not look like BioStar 2. The SDK will be
used when you want to connect directly to the device from your own
application; Your application would have to handle the connection
and the storage of data. The SDK will also allow you to use specific
API’s that are not available in the BioStar 2 API.
2
API – Swagger!
Previously, the BioStar 2 API had to be installed separately but
starting with BioStar 2.7.10, there is a new API that includes more
calls and more features that is packaged together with the install of
BioStar 2, so there is no need to install the Local API Server. The local
API server is still supported but will no longer be updated. In this
document, I will be using the new BioStar 2 API.
On a machine with BioStar 2 installed (Available from

https://www.supremainc.com/en/support/biostar-2-package.asp)
, The Swagger of the API can be accessed from
‘https://*IP_OF_MACHINE*/swagger/index.html’
After navigating to this page, you will see the below screen
You can see above (And from your screen hopefully) some examples
of API calls, you will be able to test some of these by browsing to the
IP of your machine followed by the call
3
(EG. https://*IP_OF_MACHINE*/api/access_levels/)
Browsing to this page however should bring up ‘login required’ on
the response.
To login to the API, you require a bs-session-id that will then be
passed along with the header in all future calls. We can try this
ourselves using the Swagger UI and ‘/api/login’.
NOTE: The username and password will be the admin account given
during initial setup (Username should always be ‘admin’)
If you click the ‘Try it out’ button next to parameter, you will be able
to enter your own Username and Password (This should be the one
used for logging into BioStar 2) and click execute! This just uses the
CURL command to poll the API web link. The response body will
provide information about the account that you have used to login
4
Where the response header will provide you with the bs-session-id
If you take a copy of this bs-session-id, you will be able to input it at
the top of the page under the button.
Once this has been inputted, you will be able to use the rest of the
API calls, as the swagger will automatically pass this bs-session-id
along when posting to the APIs.
5
API - Using cURL
Our API swagger is a good view of how you would go about
interacting with the BioStar 2 server, you could even do something
very simple like interacting with BioStar 2 with CMD (I added a little
bit of PowerShell to hide the password) and cURL commands!
Another option would be Postman, available at

https://www.postman.com/, this does use curl commands, but
provides a useable interface for sending and receiving responses.
For ease of use (To limit the amount of installs) I will be using cURL
directly.
cURL is simply a software project that provides a way of transferring
data (Downloading and uploading) through network protocols, an
even better point is that is comes pre-packaged with windows, so you
don’t need to download anything to use it!
When using the API swagger, clicking try it out next to any calls (Like
above) will let you edit the parameters.
6
You can then click ‘Execute’, this will send the command to the server
using cURL, you can see and take a note of the curl command below
the execute button.
Now we have a curl command, you can input this through CMD to
interact with the server, which should give the same response as the
swagger.
In the next steps, you’ll see how we can do this using only CMD.
7
API – Login!
The below batch script is an example of the login API using the curl
post generated by the swagger, where you can enter the IP of the
server (It is worth noting, to use the API with https, you will need the
SSL certificate installed on the machine), enter a username/password
and it logs you in with a curl output response that contains a valid bs-
session-id, the end of the script then outputs that line to a separate
.txt file that will be used in the next script!
@echo off
:: Prompts user for IP of the server, Sets variable then exports to a .txt file
echo Please enter IP of server:
set /P IP=
del IP.txt 2>NUL
@echo %IP%> IP.txt
echo.
::Prompts user for Username input and sets as variable
echo Please enter Username:
set /P UserID=
echo.
::Prompts user for password input but hides the characters using PowerShell, then sets as variable
powershell -Command $pword = read-host "Enter password" -AsSecureString ; ^
$BSTR=[System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($pword) ; ^
[System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR) > .tmp.txt
set /p UserPW=<.tmp.txt & del .tmp.txt
::Uses cURL to sent the command to server, using variables inputted above, exports to curloutput.txt
curl -X POST "https://%IP%/api/login" -H "accept: application/json" -H "Content-Type: application/json"

-d "{ \"User\": { \"login_id\": \"%UserID%\", \"password\": \"%UserPW%\" }}" -o curloutput.txt -i
::Searches curloutput.txt for the BS-Session-ID Line and exports it singularly to a .txt file.
del BSSession.txt 2>NUL
findstr /b /r "bs-session-id" curloutput.txt >>BSSession.txt
8
API – Add User!
The below batch script is again very simplistic but allows you to input
a user into BioStar 2 using the curl command generated by the
swagger. It first uses the BSSession.txt generated by the Login script
previously used and sets this as a variable, you then just need to
enter the ID, name and email of the new user.
@echo off
:: Uses files previously generated using API Login.cmd to set IP and BS-Session-ID
set /P IPAddress= <IP.txt
set /P bssession= <BSSession.txt
::Prompts for userID of user to be added
echo Please enter New User ID:
set /P ID=
echo.
::Prompts for name of User to be added
echo Please enter Name:
set /P Name=
echo.
::Prompts for email of user to be added
echo Please enter Email:
set /P Email=
echo.
::Puts all of the above through a curl command
curl -X POST "https://%IPAddress%/api/users" -H "accept: application/json" -H "%bssession%" -H

"Content-Type: application/json" -d "{ \"User\": { \"name\": \"%name%\", \"email\": \"%email%\",
\"user_id\": \"%ID%\", \"user_group_id\": { \"id\": \"1\" }, \"disabled\": \"false\",
\"start_datetime\": \"2001-01-01T00:00:00.00Z\", \"expiry_datetime\": \"2030-12-
31T23:59:00.00Z\", \"cards\": [] }}"
9
This is setting the basics of the user, as within this, I have set ‘User
group ID’ to always be ‘1’, as well the start and expiry to the default
BioStar 2 values (2001 – 2030).
10

How To Get Started With Biostar 2 Api: Compiled by George Cartlidge

Uploaded by

Copyright:

Available Formats

How To Get Started With Biostar 2 Api: Compiled by George Cartlidge

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

How To Get Started With Biostar 2 Api: Compiled by George Cartlidge

Uploaded by

Copyright:

Available Formats

How to get started with

An API is a set of functions that allows you to interface with an

On a machine with BioStar 2 installed (Available from

If you take a copy of this bs-session-id, you will be able to input it at

the top of the page under the button.

Another option would be Postman, available at

echo Please enter IP of server:

del IP.txt 2>NUL

@echo %IP%> IP.txt

::Prompts user for Username input and sets as variable

echo Please enter Username:

powershell -Command $pword = read-host "Enter password" -AsSecureString ; ^

[System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR) > .tmp.txt

set /p UserPW=<.tmp.txt & del .tmp.txt

curl -X POST "https://%IP%/api/login" -H "accept: application/json" -H "Content-Type: application/json"

del BSSession.txt 2>NUL

findstr /b /r "bs-session-id" curloutput.txt >>BSSession.txt

set /P IPAddress= <IP.txt

set /P bssession= <BSSession.txt

::Prompts for userID of user to be added

echo Please enter New User ID:

::Prompts for name of User to be added

echo Please enter Name:

::Prompts for email of user to be added

echo Please enter Email:

::Puts all of the above through a curl command

curl -X POST "https://%IPAddress%/api/users" -H "accept: application/json" -H "%bssession%" -H

You might also like

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.