armorapi 0.0.3

module for working with the armorapi

Armor Python API Auth wrapper

What is it

This package provides a simple python interface for interacting with the Armor.com API. It provides a simple mechanism for authentication and making API requests. Specific API requests are down to the developer, this package simply provides authentication mechanisms and the means to make requests.

Installation

From PyPi $ pip install armorapi

Use

Authentication

The package provides both v1 and v2 authentication. v1 authentication is the default method. v2 authentication requires MFA, v1 does NOT.

v1 authentication

from armorapi import *
aa = ArmorApi(username,password)

v2 authentication

from armorapi import *
aa = ArmorApi(username,password,auth=2)

v1 authorisation tokens are valid for 15 minutes, the api object provides a simple means to reissue a token, this updates the authorisation token value to be sent with the next request:

aa.v1_reissue_authorisation_token()

Reissuing of tokens is performed in a thread safe manner, therefore v1 token reissue can be set in a separate threading.timer thread for a seamless update process (in the case of this example every 10 minutes):

import threading
from armorapi import *
aa = ArmorApi(username,password,auth=2)

timer = threading.timer(600, aa.v1_reissue_authorisation_token)
timer.start()

V2 authentication doesn't have a token reissue mechanism.

The api object handles by default 4 authentication failures every 10 minutes, i.e. if a 401 http response code is returned it will attempt to reauthenticate, but will only do this in 4 times in a 10 minute period before causing an exception. The number of attempts before exception in a 10 minute period can be set as desired:

from armorapi import *
aa = ArmorApi(username,password, retries401=8)

Account IDs

By default the api object will use the first Armor account ID assigned to the user authenticating without the user needing to set and account ID. In many cases this will be fine as generally users are only assigned to one account, but in cases where a user has multiple accounts a specific account can be selected at instantiation:

from armorapi import *
aa = ArmorApi(username,password, accountid=<account_id>)

api requests

The api object has the public method 'make_request' available, intended for making api requests

from armorapi import *
aa = ArmorApi(username,password)
response = aa.make_request('https://api.armor.com/me')

make_request performs a GET request by default, POST and PUT are also available methods, post and put requests accept a data input of json like data made up of dictionaries and/or lists.

from armorapi import *
aa = ArmorApi(username,password)
response = aa.make_request('https://api.armor.com/me', method='POST', data={'key': 'value', 'key2': 'value2'})

HTTP Headers and more

Although the api object sets account and authorisation headers, many API requests rely on custom http headers in both the request and response. the api object levarages the python requests module, specifically a requests session. All requests session methods and members are available for use, see the requests doucmentation for further advance use. https headers can be added at the session level so the header persists across requests:

from armorapi import *
aa = ArmorApi(username,password)
aa.session.headers.update({'Range': 'entities=0-10; max=10'})

If a header value is only needed for a single request dict type values can be passed with make_request method, the values will be merged with the session-level values that are set. The method-level parameters override session parameters. Method-level parameters will not be persisted across requests:

from armorapi import *
aa = ArmorApi(username,password)
response = aa.make_request('https://api.armor.com/me', headers={'Range': 'entities=0-10; max=10'})

`

api responses

Returned responses are requests.Response objects, please see the linked requests documentation for full details, however key features are:

• Response.json() returns the json encoded content of the response.
• Response.headers a dict of response headers.

from pprint import pprint
from armorapi import *
aa = ArmorApi(username,password)
response = aa.make_request('https://api.armor.com/me')
response.headers
    {'Content-Length': '1221', 'Content-Type': 'application/json; charset=utf-8', 'Server': 'Microsoft-HTTPAPI/2.0'}
pprint(response.json())
    {'accounts': [{'accountType': 'Direct',
               'currency': 'USD       ',
               'id': 0007,
               'isSynced': True,
               'name': 'Documentation Example Account',
               'parent': 1,
                ....