RS2 REST API v7.0.0 - RS2 Technologies

[Pages:15]RS2 REST API v7.0.0.x User's Guide

Last Update: 2/27/2019 4:29PM

Release Notes

3

Requirements

3

Introduction

3

Swagger/OpenAPI and Client Code Generation

4

Abbreviations/Glossary of Terms

5

API Notes

5

General

5

GET (lists) versus GET (single item)

5

PUT

6

Alarms

6

PUT /v1.0/Alarms/{id}

6

Badges

6

GET /v1.0/Badges

6

Filter Parameter

6

OrderBy Parameter

7

LastCardTimestamp and LastCardholderTimestamp Parameters

8

GET /v1.0/Badges/LastModification

8

Cards

8

GET /v1.0/Cards

8

POST v1.0/Cards/{id} and PUT v1.0/Cards{id}

9

Card Event Reporting - CardEvents with PUT/POST

9

Cardholders

10

POST v1.0/Cardholders/{id} and PUT v1.0/Cards/{id}

10

Columns

10

GET /v1.0/Columns/{tableName}

10

Messages - Events, Alarms and Change of State Notifications

10

Polling

10

SignalR

10

Message Data

11

Release Notes

? Web API version increased to 7.0.0.x to coincide with the version of Access It!

Requirements

? HTTPS is now required to use the Web API. ? The Web API must be activated on the Access It dongle. ? A client key must be entered into the system, using either the thick client or the web

client, in order to activate the Web API. (Provided by RS2) ? A seperate Public Key must be passed with all calls to the API for the call to work.

(Provided by RS2)

Introduction

The RS2 REST API can be used for the following purposes:

Fetch system data including hardware settings and events. Update system data such as reader and card settings. Execute commands on hardware such as unlocking a door or executing a macro.

There is comprehensive online documentation available and that should be the first point of reference for a developer looking to integrate with the API. This document is intended to provide additional notes and information that could not easily be included in the online documentation.

If the Web API feature is enabled and the Access It! service is running then the online documentation will be available at the following URL:

http://(Access It! Server):(Port)/swagger/ui/index

Note that the Web API port is 55459 by default but can be set to a different number within the Access It! Universal software from the "Edit Server" screen.

Accessing the above URL will provide a list of available API calls as shown below:

Clicking on each item in the list will reveal more details about the API calls available for each area of the API (Alarm, Badge, etc.). It is possible to send GET/POST/PUT commands directly using the above web interface. Basic authentication is used for all calls and we strongly recommend using SSL (https) in production. A valid Access It! username/password must be supplied when executing each command. A permission check will be applied to each REST call according to the username provided.

Swagger/OpenAPI and Client Code Generation

Swagger (also known as OpenAPI) is an API description format for REST APIs. It is analogous to the WSDL document format that is often used to describe a SOAP-based web service. For more information see .

The Swagger/OpenAPI description document (in JSON format) for RS2's REST API can be viewed here:

http://(Access It! Server):(Port)/swagger/docs/v1.0

This JSON document can easily be imported into the Postman application (see: ) if desired. Postman provides another way to quickly try out the API.

The Swagger description document can also be used to generate client code in many languages using Swagger-CodeGen (see: ). Alternatively, a developer can write their own custom code to execute HTTP GET/PUT/POST commands if preferred.

Abbreviations/Glossary of Terms

The reader can learn more about Access It! by using the help documentation that is included with that software (accessed using the File -> help menu item). This will help with understanding basic terminology such as "Timezone", "Interval", "Precision Access", and "Access Level". The reader should also be aware of the following abbreviations and/or terms that are used within the API:

SCP

Abbreviation

SIO

CP (e.g. CPNumber) ACR (e.g. ACRNumber) MP (e.g. MPNumber) Ack (e.g. SecureAck)

Meaning

System Control Processor board (main board)

System Input/Output board (typically used to provide extra inputs/outputs/readers)

Output (e.g. Output Number)

Reader (e.g. Reader Number)

Input (e.g. Input Number)

Acknowledgement (e.g. Secure Acknowledgement)

API Notes

General

GET (lists) versus GET (single item)

There are often two different GET requests per item - one that returns a list of items and another that returns a single item. For some items the GET request that returns a list (e.g. list of cards) does not return as much item data as the GET request for a single item (e.g. a single card). This

is by design in order to improve performance for the list request. If full information is needed on each item then it can be fetched using the item-specific GET for each item.

PUT

When creating a new item such as a new card (using the POST operation) the data for the new item should be passed in the body of the HTTP request. The following data can be omitted:

The primary key for the item. This can be set to null or the empty GUID. For example it is not necessary to provide a CardID when creating a new card. The primary key will be generated by the system.

Last modified (date). This will be generated by the system. Last modified by User (string). This will be generated by the system.

TODO: Check for any Enums that aren't already described and document them here.

TODO: Go through all of the controllers and document any unusual/unexpected business rules or behavior.

Alarms

PUT /v1.0/Alarms/{id}

This call is used to either acknowledge or clear an alarm.

If the alarm has not yet been acknowledged then it will be acknowledged. If the alarm has already been acknowledged then it will be cleared.

Badges

GET /v1.0/Badges

Filter Parameter The optional "filter" querystring parameter is used to filter down the results and is based on the oData filter (see: section 4.5).

Examples filter=cardnumber eq 123 filter=cardnumber ne 55 filter = lastname eq smith filter=startswith(lastname, `jo')

filter=startswith(lastname, jo) (note that single quotes are optional around strings) filter=cardnumber eq 123 and startswith(lastname, smit) filter=(cardnumber eq 123) and (startswith(lastname, smit)) filter=(cardnumber eq 123) or (startswith(lastname, smit)) filter=cardnumber ge 1000 filter=datecreated gt datetime'2018-06-19T01:30:00'

Notes on data values: Strings can be enclosed in single quotes if desired but this is not required. A datetime value should be written as follows: datetime'yyyy-mm-ddThh:mm:ss'. For example: datetime'2018-07-04T09:00:00' which represents 9AM on July 4th 2018 local time. Only local times are currently supported, it is not possible to specify a timezone.

Allowed filter operators (note that operators are not case sensitive in the URL): String operators:

StartsWith(fieldname, string) SubstringOf(fieldname, string) EndsWith(fieldname, string)

Comparison operators (can be used to filter numeric/datetime/character fields): Gt (greater than) Lt (less than) Eq (equal) Ne (not equal) Ge (greater than or equal to) Le (less than or equal to)

Logical operators (used to apply multiple statements): Or (logical OR) And (logical AND)

Parentheses ( ) can be used to group logical statements together, as shown in the examples above.

OrderBy Parameter Examples:

?orderby=LastName,FirstName ?orderby=DateCreated,LastName,FirstName ?orderby=CardNumber

The items will be returned sorted on the specified fields, in ascending order.

LastCardTimestamp and LastCardholderTimestamp Parameters NOTE: when one or the other of these parameters is specified the other parameters in the query string will be ignored.

The LastCardTimestamp and LastCardholderTimestamp parameters can be used to only fetch badges where the card or cardholder has been updated since the provided timestamps. The timestamp parameter is a base-64 encoding of a row version number. Row row version numbers are increased each time a row is changed. (Note that despite the name, Timestamp parameters do not contain date or time information.)

Example timestamp: AAAAAAAD79U= which when base-64 decoded is 0x000000000003EFD5

See the information below on the GET /v1.0/Badges/LastModification call for details on how to fetch the most recent time stamps for cards and cardholders.

GET /v1.0/Badges/LastModification

This call returns LastCardTimestamp and LastCardholderTimestamp values which can then be passed as querystring parameters to the GET /v1.0/Badges call. This allows the client to only return badges that were added or updated after the last card/cardholder timestamp (i.e. newly added or modified records only).

Cards

GET /v1.0/Cards

The following sets of enumerated values are referenced in the card data:

IPLocksetUserType enum: 1 - Master User 2 - Emergency User 3 - Deadbolt Override 4 - Regular User 5 - Extended User 6 - Passage User 7 - Use Limit User 8 - Panic User 9 - Lockout User 10 - Relock User 11 - Notify User 12 - Comm User 13 - Suspended User

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download