HTTP REST API – basic information and example of communication with API of 2N® Access Commander

In 2N® Access Commander, there is available HTTP REST API which gives the opportunity to completely control 2N® Access Commander, including read, modify, create or delete data from it.

Prerequisities and technical information about HTTP REST API in Access Commander

API serves for integration purposes with any possible 3rd party systems in real-time, since no direct access to Access Commander's database is provided:

How to find out what command to send a to HTTP REST API

Let’s say we would like to login to Access Commander using an API in order to be able to use other commands.

We can easily see how it can be done on the web of 2N Access Commander itself because the web page of Access Commander is using the same HTTP REST API to access all data.

The following procedure will show how you can see which commands and parameters are used for each operation with data:

•  load the Access Commander’s web ´page in your web browser and open the web browser's debug console by pressing F12 -> Network -> XHR (same for Chrome and Firefox browser).
  This will show a console in your web browser where we can see all the commands as you can see on the image below:
  
  
  
  
• In order to see which command with which parameters is sent to API for login request, fill in login name and password in your web browser with enabled debugging console from previous step and press LOGIN button.
  
  
• Access Commander will login in and in the web browser's debug console you can see multiple requests and one of them is the login request we are looking for:  

• Select mentioned login request by clicking on it.
  In its Header you can see it uses PUT method
  In its Header you can see which endpoint it calls (/login)
  In its Request you can see which in which syntax data are sent.
  Using those data from web browser you can easily replicate this command in your application.
  
  
  After successful login, you will be also able to see in Response cookie required for commands which will follow

How to use commands from your application

To demonstrate this example we will use an application known as POSTMAN which is able to send HTTPS commands and read responses to its requests.

• For the first time using the Access Commander after importing the appliance, it is needed to use the web interface to login as the administrator ("Admin") to change the default password ("2n")
• While accessing the Access Commander using the REST API and using for example the app Postman, please, disable the SSL certificate verification first. There is no domain that can sign the certificate and a self-signed is not considered as trusted automatically by default.
• Open the Postman and fill in the header as you saw in the previous example from your web browser debug console. Fill in also Body with request data you could see in the previous example. Don’t forget to set Method as PUT and Body as JSON.

• Once you send the data to Access Commander API, when login is successful you will receive 200 OK a response along with other data and authentication cookies.

Examples of commands and operations using HTTP REST API

In this section, we are ready to post the commands. First of all, we use the valid credentials to login:

(Let's consider we have an Access Commander using an IP 192.168.0.250, username: Admin, Password: Admin1234)

Login command

Command:

PUT https://192.168.0.250/api/v2/login

Body(data to be sent):

{"login":"Admin","password":"Admin1234","longTimeLogin":true}

____________________________________________________________________________________________________________________________________________________

List of current users

Now we want to receive a list of users with all the parameters

Command:

GET https://192.168.0.250/api/v2/users

Body(data to be sent):
{}

____________________________________________________________________________________________________________________________________________________

Getting information about a specific user

Each user has a unique ID called UUID. It is possible to get from the previous command.

(Lets say our user has a UUID: e7207ded-b864-424b-ad0f-e06b9d8f7527)

Command:

GET https://192.168.0.250/api/v2/users/e7207ded-b864-424b-ad0f-e06b9d8f7527

____________________________________________________________________________________________________________________________________________________

Creating a new user

Now we want to create a new user with the name UserAPI. This user will belong to the company with the ID=1

Command:

POST https://192.168.0.250/api/v2/users

Body(data to be sent):

{"Name":"UserAPI","Company":{"Id":1}}

In the answer, there will be a parameter E.G.: "ID": "09e7eab1-7b80-4071-89c9-4969a61354e1"

____________________________________________________________________________________________________________________________________________________

Adding a user to a group

We need to know first the name of the group we want to add the user to.

Command:
GET https://192.168.0.250/api/v2/groups

Answer:
{
    "count": 1,
    "data": [
        {
            "Name": "Home",
            "Id": "511720dc-ef0b-4e7c-b63a-4a54b350792d",
            "ModifiedGuid": 0,
            "Company": {
                "Id": 1,
                "Name": "My Company"
            },
            "Users": [],
            "VisitorCards": []
        }
    ]
}

After that, we can use the answer for adding the user to the specific group:

Command:

PUT https://192.168.0.250//api/v2/users/4edab7c2-a6fc-45e8-af21-2542a21b26f7/groups

Body(data to be sent):
[{"Id":"511720dc-ef0b-4e7c-b63a-4a54b350792d"}]

____________________________________________________________________________________________________________________________________________________

Adding new RFID card for existing user

If there is no card added yet, first you need to read user GUID first and then use it in command to add the card for that user.  ModifiedGUID is not needed when user has no card added yet on that position.

Command:

POST https://192.168.0.250/api/v2/users/09e7eab1-7b80-4071-89c9-4969a61354e1/cards

Body(data to be sent):

{"Identification":"12345678"}

____________________________________________________________________________________________________________________________________________________

Updating RFID card (similar for other parameters)

First you need to read user GUID and then use it in command to modify the card for that user.
For maintaining database consistency, we need to use a specific ID for each parameter to prevent multiple processes from modifying data at the same time. This is called ModifiedGUID and we need to get this information from the parameter before we change it. Let's say another process changed the RFID card number 3 times already to the number 12342622. We are going to find out this now.

Command:

GET https://192.168.0.250/api/v2/users/09e7eab1-7b80-4071-89c9-4969a61354e1

Answer:

"Cards": [
            {
                "Identification": "12342622",
                "Description": "",
                "Id": "25d79b1f-8612-4c44-859b-e04f89e19bb5",
                "ModifiedGuid": 3
            }

Now we know the ModifiedGUID=3 and we can change the card number to 12121212 (note: we are adding the ID of the card position to the URL):

Command:

PUT https://192.168.0.250/api/v2/users/09e7eab1-7b80-4071-89c9-4969a61354e1/cards/25d79b1f-8612-4c44-859b-e04f89e19bb5

Body(data to be sent):
{"Identification":"12121212","ModifiedGuid":3}

____________________________________________________________________________________________________________________________________________________

Creating 2 codes for a user (1234, 9876) (Note: Ordinal = ID of a code)

Command:

POST https://192.168.0.250/api/v2/users/09e7eab1-7b80-4071-89c9-4969a61354e1/codes

Body(data to be sent):
{"SwitchCode":"1234","User":{"Id":"e7207ded-b864-424b-ad0f-e06b9d8f7527"},"Ordinal":0}

Command:
POST https://192.168.0.250/api/v2/users/09e7eab1-7b80-4071-89c9-4969a61354e1/codes

Body(data to be sent):
{"SwitchCode":"9876","User":{"Id":"e7207ded-b864-424b-ad0f-e06b9d8f7527"},"Ordinal":1}

____________________________________________________________________________________________________________________________________________________

Deleting the 2nd code

We need to know the code ID the ModifiedGuid first:
Command:
GET https://192.168.0.250/api/v2/users/09e7eab1-7b80-4071-89c9-4969a61354e1

Answer:

 
 "Codes": [
            {
                "Ordinal": 0,
                "SwitchCode": "1234",
                "Id": 4,
                "ModifiedGuid": 0,
                "Collisions": []
            },
            {
                "Ordinal": 1,
                "SwitchCode": "9876",
                "Id": 5,
                "ModifiedGuid": 0,
                "Collisions": []
            }
        ],

To the URL we need to put the ID of the code we want to delete.

Command:
DELETE https://192.168.0.250/api/v2/users/09e7eab1-7b80-4071-89c9-4969a61354e1/codes/5
 
Body(data to be sent):
{"Identification":"9876","ModifiedGuid":0}