API Reference

Overview

gRPC

The APIs of G-SDK are defined using gRPC to maximize its compatibility among programming languages. And, gRPC uses protocol buffers as the Interface Definition Language (IDL) for describing both the service interface and the structure of the payload messages. Since the naming convention and data types of each language are different, you have to consult the generated header files in addition to these definitions.

Device gateway vs. master gateway

A master gateway manages devices through one or more device gateways. Due to this difference, the Connect Master API is different from the Connect API. And, since the master gateway is designed for multi-tenant systems, you have to use the Login API before using other APIs. The Tenant API and the Gateway API are also provided for the master gateway only. Apart from these differences, the other APIs are same both for the device gateway and the master gateway.

API	Device Gateway	Master Gateway	Note
Connect	O	X	manage devices directly
Connect Master	X	O	manage devices via device gateways
Login	X	O	login as an administrator or a tenant
Tenant	X	O	manage tenants
Gateway	X	O	manage device gateways
Server	O	X	implement server matching
UDP	O	X	manage devices directly
UDP Master	X	O	manage devices via device gateways

API definition

Each API sends a single request to the gateway and gets a single response back.

service Connect {
  rpc Connect(ConnectRequest) returns (ConnectResponse);
}

message ConnectRequest {
  ConnectInfo connectInfo;
}

message ConnectResponse {
  uint32 deviceID;
}

For brevity, when the response has no data, its definition is omitted in the reference manual.

XXX_Multi command

One of the design goals of G-SDK is to manage hundreds of devices easily. The more devices, the more cumbersome for developers to do same operations repetitively on multiple devices. To alleviate this overload, G-SDK provides XXX_Multi commands. For example, with User.EnrollMulti, you can enroll users to multiple devices with only one function call. All these operations will be executed in parallel by the gateway.

For these commands, if the operation fails on any of the target devices, the following deviceErrors will be returned. Getting these information will vary according to the client language. See the user synchronization example of the client SDK for details.

Response

Parameter	Type	Description
deviceErrors	ErrorResponse[]	The errors on some of the target devices

Since the responses of all XXX_Multi commands have same definition, they are also omitted in the manual.

Core APIs

Connect

Manage connections between the device gateway and the devices.

ConnectMaster

Manage connections between the master gateway and the devices through device gateways.

Device

Provide the firmware and capability information of a device. Lock, reset, or upgrade devices.

Event

Read event logs from a device. Enable monitoring and receive real-time events from devices.

Network

Configure the IP address of a device.

User

Enroll and manage users. Set fingerprints, cards, and access groups to users.

Master gateway APIs

Gateway

Manage device gateways for the master gateway.

Tenant

Manage tenants for the master gateway. Only an administrator can use these APIs.

Authentication APIs

Auth

Configure the options related to credentials such as cards and fingerprints.

Card

Read or write a card. You can also configure the options related to authenticating cards.

Finger

Scan a fingerprint. You can also configure the options related to authenticating fingerprints.

Face

Scan face templates. You can also configure the options related to authenticating faces.

Server

Implement server matching.

Access control APIs

You can specify which users can access which doors for specific schedules.

Access

Configure access levels and access groups.

Door

Configure doors and manage them.

Lift

Configure lifts and manage them.

Schedule

Make schedules, which will be used for access control and other configurations.

T&A APIs

T&A

Configure the options related to time & attendance. You can also get event logs with time & attendance or job code information.