Python client documentation

Source code documentation:

Alignak REST backend client library

This module is a Python library used for connecting to an Alignak backend.

The Backend class implements the necessary methods to establish a connection and interact with the backend REST API.

Backend interaction will necessarily start with a login and end with a logout. In between, using the get, post, patch and delete functions will allow to manipulate the backend elements.

The Alignak backend data model is documented here.

Backend class

class alignak_backend_client.client.Backend(endpoint, processes=1)[source]

Bases: object

Backend client class to communicate with an Alignak backend

Provide the backend endpoint URL to initialize the client (eg. http://127.0.0.1:5000)

static decode(response)[source]

Decodes and returns the response as JSON (dict) or raise BackendException :param response: requests.response object :return: dict

delete(endpoint, headers)[source]

Method to delete an item or all items

headers[‘If-Match’] must contain the _etag identifier of the element to delete

Parameters:
  • endpoint (str) – endpoint (API URL)
  • headers (dict) – headers (example: Content-Type)
Returns:

response (deletion information)

Return type:

dict

get(endpoint, params=None)[source]

Get items or item in alignak backend

If an error occurs, a BackendException is raised.

This method builds a response as a dictionary that always contains: _items and _status:

{
    u'_items': [
        ...
    ],
    u'_status': u'OK'
}
Parameters:
  • endpoint (str) – endpoint (API URL) relative from root endpoint
  • params (dict) – parameters for the backend API
Returns:

dictionary as specified upper

Return type:

dict

get_all(endpoint, params=None)[source]

Get all items in the specified endpoint of alignak backend

If an error occurs, a BackendException is raised.

If the max_results parameter is not specified in parameters, it is set to BACKEND_PAGINATION_LIMIT (backend maximum value) to limit requests number.

This method builds a response that always contains: _items and _status:

{
    u'_items': [
        ...
    ],
    u'_status': u'OK'
}
Parameters:
  • endpoint (str) – endpoint (API URL) relative from root endpoint
  • params (dict) – list of parameters for the backend API
Returns:

dict of properties

Return type:

dict

get_domains()[source]

Connect to alignak backend and retrieve all available child endpoints of root

If connection is successful, returns a list of all the resources available in the backend: Each resource is identified with its title and provides its endpoint relative to backend root endpoint.:

[
    {u'href': u'loghost', u'title': u'loghost'},
    {u'href': u'escalation', u'title': u'escalation'},
    ...
]

If an error occurs a BackendException is raised.

If an exception occurs, it is raised to caller.

Returns:list of available resources
Return type:list
get_response(method, endpoint, headers=None, json=None, params=None, data=None)[source]

Returns the response from the requested endpoint with the requested method :param method: str. one of the methods accepted by Requests (‘POST’, ‘GET’, …) :param endpoint: str. the relative endpoint to access :param params: (optional) Dictionary or bytes to be sent in the query string for the Request. :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the Request. :param json: (optional) json to send in the body of the Request. :param headers: (optional) Dictionary of HTTP Headers to send with the Request. :return: Requests.response

get_token()[source]

Get the stored backend token

get_url(endpoint)[source]

Returns the formated full URL endpoint :param endpoint: str. the relative endpoint to access :return: str

login(username, password, generate='enabled', proxies=None)[source]

Log into the backend and get the token

generate parameter may have following values: - enabled: require current token (default) - force: force new token generation - disabled

if login is: - accepted, returns True - refused, returns False

In case of any error, raises a BackendException

Parameters:
  • username (str) – login name
  • password (str) – password
  • generate (str) – Can have these values: enabled | force | disabled
  • proxies (dict) – dict of proxy (http and / or https)
Returns:

return True if authentication is successfull, otherwise False

Return type:

bool

logout()[source]

Logout from the backend

Returns:return True if logout is successfull, otherwise False
Return type:bool
patch(endpoint, data, headers=None, inception=False)[source]

Method to update an item

The headers must include an If-Match containing the object _etag.
headers = {‘If-Match’: contact_etag}

The data dictionary contain the fields that must be modified.

If the patching fails because the _etag object do not match with the provided one, a BackendException is raised with code = 412.

If inception is True, this method makes e new get request on the endpoint to refresh the _etag and then a new patch is called.

If an HTTP 412 error occurs, a BackendException is raised. This exception is: - code: 412 - message: response content - response: backend response

All other HTTP error raises a BackendException. If some _issues are provided by the backend, this exception is: - code: HTTP error code - message: response content - response: JSON encoded backend response (including ‘_issues’ dictionary …)

If no _issues are provided and an _error is signaled by the backend, this exception is: - code: backend error code - message: backend error message - response: JSON encoded backend response

Parameters:
  • endpoint (str) – endpoint (API URL)
  • data (dict) – properties of item to update
  • headers (dict) – headers (example: Content-Type). ‘If-Match’ required
  • inception (bool) – if True tries to get the last _etag
Returns:

dictionary containing patch response from the backend

Return type:

dict

post(endpoint, data, files=None, headers=None)[source]

Create a new item

Parameters:
  • endpoint (str) – endpoint (API URL)
  • data (dict) – properties of item to create
  • files (None) – Not used. To be implemented
  • headers (dict) – headers (example: Content-Type)
Returns:

response (creation information)

Return type:

dict

put(endpoint, data, headers=None, inception=False)[source]

Method to replace an item

The headers must include an If-Match containing the object _etag.
headers = {‘If-Match’: contact_etag}

The data dictionary contain all fields.

If the puting fails because the _etag object do not match with the provided one, a BackendException is raised with code = 412.

If inception is True, this method makes a new get request on the endpoint to refresh the _etag and then a new put is called.

If an HTTP 412 error occurs, a BackendException is raised. This exception is: - code: 412 - message: response content - response: backend response

All other HTTP error raises a BackendException. If some _issues are provided by the backend, this exception is: - code: HTTP error code - message: response content - response: JSON encoded backend response (including ‘_issues’ dictionary …)

If no _issues are provided and an _error is signaled by the backend, this exception is: - code: backend error code - message: backend error message - response: JSON encoded backend response

Parameters:
  • endpoint (str) – endpoint (API URL)
  • data (dict) – properties of item to update
  • headers (dict) – headers (example: Content-Type). ‘If-Match’ required
  • inception (bool) – if True tries to get the last _etag
Returns:

dictionary containing put response from the backend

Return type:

dict

set_token(token)[source]

Set token in authentification for next requests :param token: str. token to set in auth. If None, reinit auth

token

Get the stored backend token

BackendException class

exception alignak_backend_client.client.BackendException(code, message, response=None)[source]

Bases: exceptions.Exception

Specific backend exception class. This specific exception is raised by the module when an error is encountered.

It provides an error code, an error message and the backend response.

Defined error codes:

  • 1000: first stage error, exception raising between the client and the backend when connecting
  • <1000: second stage error. Connection between client and backend is ok,

but the backend returns errors on requests