Package: gallagher
Currently under heavy development, please check for stable release before useGallagher Command Centre REST API ClientPython idiomatic client for Gallagher Command Centre APIGallagher Security manufacture a variety ofsecurity productsall of which are controlled by theirCommand Centresoftware. Traditionally Command Centre has been a Windows based server product. Version8.6introduced a REST API which allows you to interact with the system via HTTP requests. Gallagher also provide aCloud API Gatewaywhich allows third party integrations to securely communicate with the Command Centre on site.This API client is a Python wrapper around their REST API and is designed to work locally or via the Cloud API Gateway.While Gallagher maintain a set ofSwagger definitionsfor their API, they are primarily intended to generate the documentationpublished on Github. They use a tool calledSpectacle. Gallagher explicitly state that the Swagger definitions are not intended to be used to generate code. Due to this the API client is hand built and not auto-generated.Due to custom annotations the YAML files will not parse with any standard parser.The client was designed while building products around the Gallagher API. It's design is highly opinionated and does not conform with how Gallagher design software interfaces. If you've worked withstripe-pythonthe syntax may feel familiar.fromgallagherimportcc,constcc.api_key="GH_"cc.discover()cc.Customer.create()Note this project isNOTofficially affiliated with Gallagher SecurityAPI NotesThe Gallagher API useshrefattributes to provide a the destination of referenced objects in the responses. These are prefixed with the server origin i.e if you are using the Cloud Gateway then all your URLs will be prefixed with the appropriate gateway's address.These appear in various forms, starting from as simple as thehrefitself:"cardholders":{"href":"https://localhost:8904/api/access_groups/352/cardholders"}through to self recursive references with additional attributes:"parent":{"href":"https://localhost:8904/api/access_groups/100","name":"All R&D"}Above examples have been taken from the Gallagher documentationOurschemasprovide a set ofMixinsthat are used to construct the Models. These are repeatable patterns that need not be repeated. The typical patter would be to subclass from theMixinse.g:from.utilsimportAppBaseModel,IdentityMixin,HrefMixinclassAccessGroupRef(AppBaseModel,HrefMixin):""" Access Groups is what a user is assigned to to provide access to doors"""name:strwhere theHrefMixinprovides thehrefattribute:classHrefMixin(BaseModel):""" HrefThis mixin is used to define the href field for allresponses from the Gallagher API."""href:strTheseMixinclasses can also be used to declare attributes that seek to use the same pattern:classDivisionDetail(AppBaseModel,IdentityMixin,):""""""name:strdescription:Optional[str]server_display_name:strparent:Optional[HrefMixin]whereparentis simply anhrefwithout any other attributes. In the cases where these attributes have more than just anhrefwe definedReferenceclasses:classAccessGroupRef(AppBaseModel,HrefMixin):""" Access Groups is what a user is assigned to to provide access to doors"""name:strand use them to populate the attributes:classVisitorTypeDetail(AppBaseModel,IdentityMixin):""""""access_group:AccessGroupRefhost_access_groups:list[AccessGroupSummary]visitor_access_groups:list[AccessGroupSummary]In this example theAppGroupRefhas anameattribute which is not present in theHrefMixinclass.Please see the schema section for naming conventions forschemaclassesDesignThis API client primarily depends on the following libraries:httpx, fo transporting and parsing HTTP requestspydantic, for validating responses and constructing request bodiesWe useTaskfileto automate running tasks.The project provides a comprehensive set of tests which can be run withtask test. These tests do create objects in the Command Centre, we advice you to obtain a test license.DO NOTrun the tests against a production system.Data Transfer ObjectsThere are three types of schema definitions, each one of them suffixed with their intent:RefareReferencesto other objects, they using contain ahrefand possibly additional meta data such as anameoridSummaryis what is returned by the Gallagher API in operations such assearches, these are generally a subset of the full objectDetailare the full object found at a particularhref, they compound on theSummaryschema and add additional attributesIn summary:Refsare the minimal pathway to an objectSummarybuilds on aRefand provides a subset of the attributesDetailbuilds on aSummaryand provides the full set of attributesResourcesResources arefetchable,queryable,creatable,updatableanddeletable.ResponsesResponses can be the object itself or a response layoutConfiguring the Command CentreThe following requires you to have an understanding of the Gallagher Command Centre and how to configure it. If you are unsure, please contact your Gallagher representative.Before you being, please ensure:You are running Command Centre version8.60or higher, older versions predate the gateway so cannot support itThe gateway enabled at the system levelIf it is, has the gateway been enabled for your specific API keyTo check the system level gateway status:Open the Command Centre Configuration ClientFrom theConfiguremenu, selectServices and WorkstationsFind theCommand Centre Clouditem and double-click itSwitch to theConfigurationpage, it should look something like this:To check your API key:Open the Command Centre Configuration ClientFrom theConfiguremenu, selectServices and WorkstationsFind the item that represents your REST ClientSwitch to theConnectionspage, it should look something like thisLicenseDistributed under the MIT License.