Introduction
If you’d like to use BioStar 2 New Local API as a RESTful API for your own customization or other purposes, you can simply reference this article. This article will cover the most basic usage of the BioStar 2 New Local API by C# console application.
This is just a sample application made for those who might need to use the BioStar 2 New Local API. It is a Visual C# console application.
Features
This article will cover the function below:
- Register Visual Face via Send Email API
- Register Visual Face via Face Scanning by a device (FaceStation F2)
Through this article, you can learn how to call an API function to register Visual Face to the users in BioStar 2 server. There are 2 different ways to register Visual Face via New Local API.
Make sure you take a good look at the example code of the C# program built for API calls. You can simply copy & paste the source code to use the same function in your own integration.
You can also see how to call the API functions via Postman, which is a program used for RESTful API calls.
*You must have FaceStation F2 connected to your BioStar 2.
- For the description of how to register Visual Face via Scanning by a device with BioStar 2, please visit https://support.supremainc.com/a/solutions/articles/24000060147?lang=en .
Part 1. API Call & Parameters
- Scanning Visual Face
[GET]: /api/devices/{deviceID}/credentials/face?pose_sensitivity=0&nonBlock=true
[Parameters]
Name | Type | *M/O | Explanation | Value |
|
|
|
|
|
* M – Mandatory, O – Optional
- Registering Visual Face
[PUT]: /api/users/{id}
[Parameters]
Name | Type | *M/O | Explanation | Value |
User/credentials/visualFaces | Array | O | Visual Face Information |
|
Template_ex_normalized_image | String | O | Image name in Base64 |
|
Templates | Array | O | “template_ex”, “credential_bin_type”, “template_ex_ir” |
|
Templates/template_ex | String | O | Base64 | “5” |
Templates/credential_bin_type | String | O | Credential bin type |
|
Templates/credential_ex_ir | String | O | Base64 |
|
Templates/credential_bin_type | String | O | Credential bin type | “6” |
Flag | String | O | Flag | “1” |
useProfile | String | O | Use as profile or not | True & False |
* M – Mandatory, O – Optional
Part 2. Request Body & Response Model
- Scanning Visual Face
[GET]: /api/devices/{deviceID}/credentials/face?pose_sensitivity=0&nonBlock=true
[Example Value/Parameters Model]
|
[Response Model]
{ "credentials": { "faces": [ { "raw_image": "Base64: RDQQFJYAVUYvFXsEIzIQC1QYbodkHe...", "templates": [ { "template": "Base64: RDQQFJYAVUYvFXsEIzIQC1QYbodkHe..." } ], "flag": "0" } ] }, "Response": { "code": "1003", "link": "https://support.supremainc.com/en/support/home", "message": "Success" }, "httpResponseStatus": 200 } |
[Response: Fail]
{ "Response": { "code": "262155", "link": "https://support.supremainc.com/en/support/home", "message": "not defined" } } |
[Response: Successful]
{ "credentials": { "faces": [ { "template_ex_normalized_image": "/9j/4AAQSkZJRgABAQEASABI… ", "templates": [ { "template_ex": "AAAAAAEA4gCFAe4AFQE8//7/…", "credential_bin_type": "5" }, { "template_ex_ir": "AAAAAAEAHgGPAeIAHAEAAAAASlQ7RU…", "credential_bin_type": "6" } ], "flag": "1" } ] }, "Response": { "code": "0", "link": "https://support.supremainc.com/en/support/home", "message": "Success" } } |
- Registering visual face
[PUT]: /api/users/{id}
[Example Value/Parameters Model]
{ "User": { "credentials": { "visualFaces": [ { "template_ex_normalized_image": "/9j/4AAQSkZJRgABAQEASABIAAD/…", "templates": [ { "template_ex": "AAAAAAEA+QCAAeMAJwFhAQD/XFVUQ0…", "credential_bin_type": "5" }, { "template_ex_ir": "AAAAAAEANAF+AdsAGQEAAAAASlBCRTyDfAA…", "credential_bin_type": "6" } ], "flag": "1", "useProfile": "false" } ] } } } |
[Response Model]
{ "DeviceResponse": { "rows": [ { "id": "541530887", "code": "65230" } ], "result": "false" }, "Response": { "code": "0", "link": "https://support.supremainc.com/en/support/home", "message": "Success" } } |
[Response: Fail]
{ "Response": { "code": "20", "message": "Permission not allowed" } } |
[Response: Successful]
{ "Response": { "code": "0", "link": "https://support.supremainc.com/en/support/home", "message": "Success" } } |
Part 3. Console Example
There are 2 steps to take to register Visual Face to a user. But, in the console, it is there is an additional step to choose the user which will receive the Visual Face registration.
- ScanAndRegisterVisualFace: Choose a user for Visual Face registration
- ScanVisualFace: Scan Visual Face via selected device (Must use FaceStation F2).
- RegisterVisualFaceToUser: Register the scanned Visual Face to the user chosen.
[ScanAndRegisterVisualFace]
static async void ScanAndRegisterVisualFace() { Console.WriteLine("*****ScanAndRegisterVisualFace Task Started******"); if (sessionID == null) { Console.WriteLine("You must log in first!"); return; }
CookieContainer cookieContainer = new CookieContainer();
HttpClientHandler handler = new HttpClientHandler(); handler.CookieContainer = cookieContainer;
HttpClient client = new HttpClient(handler);
client.DefaultRequestHeaders.Add("bs-session-id", sessionID); cookieContainer.Add(new Uri("https://127.0.0.1"), new Cookie("bs-session-id", sessionID)); ListUsers(); Console.WriteLine("Select User ID for Visual Face Registration..."); string userID = Console.ReadLine(); //HttpResponseMessage httpResponse = await client.GetAsync("https://127.0.0.1/api/users"); HttpResponseMessage httpResponse = client.GetAsync("https://127.0.0.1/api/users").Result;
if (httpResponse.IsSuccessStatusCode == true) { string httpResponseBody = await httpResponse.Content.ReadAsStringAsync(); //Console.WriteLine(httpResponseBody); Console.WriteLine("Registering VISUAL FACE to the USER(" + userID + ")"); ScanVisualFace(userID);
} else { Console.WriteLine("Retrieving User List Failed"); Console.WriteLine(httpResponse.ToString()); } } |
[ScanVisualFace]
- This step scans the Visual Face via selected device (FaceStation F2).
static async void ScanVisualFace(string UserID) { Console.WriteLine("*****ScanVisualFace Task Started*****"); CookieContainer cookieContainer = new CookieContainer();
HttpClientHandler handler = new HttpClientHandler(); handler.CookieContainer = cookieContainer;
HttpClient httpClient = new HttpClient(handler);
HttpClient client = new HttpClient(handler); httpClient.DefaultRequestHeaders.Add("bs-session-id", sessionID); cookieContainer.Add(new Uri("https://127.0.0.1"), new Cookie("bs-session-id", sessionID)); ListDevices(); Console.WriteLine("Select Device ID for Visual Face Scanning...(SELECT FaceStation F2..."); string deviceID = Console.ReadLine(); string resourceAddress = "https://127.0.0.1/api/devices/" + deviceID + "/credentials/face?pose_sensitivity=0&nonBlock=true";
JavaScriptSerializer serializer = new JavaScriptSerializer();
string payload = ""; Console.WriteLine(resourceAddress); StringContent sc = new StringContent(payload, Encoding.UTF8, "application/json"); //HttpResponseMessage httpResponse = await httpClient.PutAsync(resourceAddress, sc); HttpResponseMessage httpResponse = httpClient.GetAsync(resourceAddress).Result;
Console.WriteLine("SCAN YOUR VISUAL FACE with the DEVICE(ID: " + deviceID + ")");
if (httpResponse.IsSuccessStatusCode == true) { Console.WriteLine("Scan VISUAL FACE Successful."); string httpResponseBody = await httpResponse.Content.ReadAsStringAsync(); Console.WriteLine(httpResponseBody); dynamic obj = JsonConvert.DeserializeObject(httpResponseBody); string template_ex_normalized_image = obj.credentials.faces[0].template_ex_normalized_image; string template_ex = obj.credentials.faces[0].templates[0].template_ex; string template_ex_ir = obj.credentials.faces[0].templates[1].template_ex_ir; string flag = obj.credentials.faces[0].flag; RegisterVisualFaceToUser(UserID, template_ex_normalized_image, template_ex, template_ex_ir, flag); } else { Console.WriteLine("Scan VISUAL FACE Failed."); Console.WriteLine(httpResponse.ToString()); } } |
[RegisterVisualFaceToUser]
- This method receives the template values from ‘ScanVisualFace’ method and places it to ‘template_ex_normalized_image’, ‘template_ex’, ‘template_ex_ir’, and ‘flag’ values.
static async void RegisterVisualFaceToUser(string UserID, string template_ex_normalized_image, string template_ex, string template_ex_ir, string flag) { Console.WriteLine("*****RegisterVisualFaceToUser Task Started******"); if (sessionID == null) { Console.WriteLine("You must log in first!"); return; } CookieContainer cookieContainer = new CookieContainer();
HttpClientHandler handler = new HttpClientHandler(); handler.CookieContainer = cookieContainer;
HttpClient httpClient = new HttpClient(handler);
HttpClient client = new HttpClient(handler); httpClient.DefaultRequestHeaders.Add("bs-session-id", sessionID); cookieContainer.Add(new Uri("https://127.0.0.1"), new Cookie("bs-session-id", sessionID)); Console.WriteLine("Registering VISUAL FACE to USER(" + UserID + ") ...");
string resourceAddress = "https://127.0.0.1/api/users/" + UserID + ""; string payload = "{\"User\": {\"credentials\": {\"visualFaces\": [{\"template_ex_normalized_image\": \"" + template_ex_normalized_image + "\",\"templates\": [{\"template_ex\": \"" + template_ex + "\",\"credential_bin_type\": \"5\"},{\"template_ex_ir\": \"" + template_ex_ir + "\",\"credential_bin_type\": \"6\"}],\"flag\": \"" + flag + "\",\"useProfile\": \"false\"}]}}}"; StringContent sc = new StringContent(payload, Encoding.UTF8, "application/json"); //HttpResponseMessage httpResponse = await httpClient.PutAsync(resourceAddress, sc); HttpResponseMessage httpResponse = httpClient.PutAsync(resourceAddress, sc).Result;
if (httpResponse.IsSuccessStatusCode == true) { Console.WriteLine(httpResponse.ToString()); string httpResponseBody = await httpResponse.Content.ReadAsStringAsync(); Console.WriteLine("***** VISUAL FACE is now registered to " + " User " + UserID + " *****"); } else { Console.WriteLine("Failed to Register VISUAL FACE to User(" + UserID + ")"); Console.WriteLine(httpResponse.ToString()); }
} |
[Select User & Device]
Input: User ID, Device ID
[Scan your Visual Face]
[Registration Processed successfully]
Part 4. Register Visual Face via Postman
[Scan Visual Face by FaceStation F2 : Request]
*You must enter the connected FaceStation F2’s ID.
[Scan Visual Face by FaceStation F2 : Response Body: Success]
[Register Visual Face : Request]
[Register Visual Face : Successful]