netilion-api-client-py

IMPORTANT: Python does not allow dashes in module names. Consequently you can't just use the default repository name, but you have to rename the folder name, i.e.

# during cloning
git clone git@github.com:endresshauser-lp/netilion-api-client-py.git ./netilion_api_client
# - or, if using a submodule:
git submodule add git@github.com:endresshauser-lp/netilion-api-client-py.git ./netilion_api_client

Example Usage

This module is supposed to be used as a git submodule in your code (or, if you must, a plain old directory copy); if you follow the suggestion about python module names above, you should be able to use the client library like this:

# this file is alongside the full project folder, provided as a module named "netilion_api_client"
from netilion_api_client.netilion.client import NetilionTechnicalApiClient
from netilion_api_client.netilion.config import ConfigurationParameters

config = ConfigurationParameters(
    endpoint="https://api.staging-env.netilion.endress.com",
    client_id="oauth_client_id",
    client_secret="oauth_client_secret",
    username="technical user username",
    password="technical user password",
    # the following parameters are optional.
    # providing a client application saves a few API calls
    client_application_id="client_application_id",
    client_application_name="client_application_name",
    # as long as these paths remain the same ("/v1/", "/oauth/token/"), you don't need to provide these
    api_url="https://api.staging-env.netilion.endress.com/v1",
    oauth_token_url="https://api.staging-env.netilion.endress.com/oauth/token"
)

api_client = NetilionTechnicalApiClient(config)
api_client.get_assets()

API Requests

This API client implementation manages OAuth2 token exchanges and wraps requests and responses to Netilion in classes; since these have explicit implementation (as opposed to e.g. using Netilion's swagger definitions), only a subset of Netilion objects are implemented here. You can find the full Netilion API here.

Domain Model

ClientApplication; basic requirement for authentication, implemented to provide webhooks
WebHook; register some URL with a list of events in Netilion, which will then call this endpoint with a payload corresponding to the event
Asset; the basic device unit exposed through the Netilion API; can have a serial number
Unit; representation of a unit of some value. Units can be represented by either a code (e.g. metres_per_second) or an ID. When using a unit for a value, you can also use either the code or the ID - the code being easier to use.
AssetValue; a set of values generated by an asset; always has a unit and a value, but may not always have a timestamp.
AssetValues; an orthogonal representation of multiple AssetValue items, grouped by unit (instead of by asset)
AssetSystem; the representation of a system an asset may belong to. An asset can belong to any number of systems (i.e. [0, ∞]). This object currently holds only that system's specifications which may be relevant to an asset.
AssetHealthCondition; representation of a status report sent by assets. Consists of a diagnosis code for now - and notably does not contain any timestamp information (as this is not provided by Netilion).

Errors

Netilion may generate errors, either because the data transferred is incomplete, malformed, invalid or the client's technical user does not have permission to do whatever it tried to do. This leads to the following error classes thrown by validation in this library:

GenericNetilionApiError; base class for all other exceptions thrown in this module. Will try to print the JSON representation of the response or fall back to the textual representation of the response (e.g. "Response <500>").
MalformedNetilionApiResponse; Netilion sent something that doesn't meet the expectations of this library. Most likely the APIs have changed or this library has not implemented that model yet.
InvalidNetilionApiState; thrown by the library if Netilion returned data that violates an assumption, e.g. that client.find_asset(asset_id) returns exactly one asset instance, i.e. Netilion returned two or more assets.
MalformedNetilionApiRequest; the data sent to Netilion does not meet Netilion's assumptions about validity, e.g. an attribute is missing.
BadNetilionApiPermission; You are trying to access an object that does not exist or to perform an action not allowed for your user.
QuotaExceeded; the client application used for the API has exceeded its allowed quota; you either have to wait for the next billing period or upgrade your subscription.

Methods

Applications
- get_applications(); get all client applications available for this technical user
- get_my_application(); the client application we are using at this point in time
- get_application(application_id)
Assets
- get_assets()
- get_asset(asset_id)
- create_asset(serial_number, product_id)
- delete_asset(asset_id)
- find_asset(serial_number); following the API to the letter, this may return more than one item!
- set_rw_permissions(asset_id, user_id)
Units
- find_unit(unit_code); following the API to the letter, this may return more than one item!
- get_unit(unit_id)
AssetValue(s)
- get_asset_values(asset_id); this should return the last set of values published by this asset.
- push_asset_values(asset_values); be advised that this uses AssetValues and not the AssetValue model class.
WebHooks
- get_webhooks()
- set_webhook(webhook)
- get_webook(webhook_id)
AssetSystem
- get_asset_systems(asset_id)
AssetHealthCondition
- get_asset_health_conditions(asset_id); for a list of health conditions.
- get_asset_health_condition(health_condition_id); for details. Does not include the asset id!

You can also directly access the verb methods (.get(), .post(), .delete(), ...) provided by the base OAuth2Session, tokens will be managed regardless.

Good-To-Knows

All methods are type-hinted, so have a look at exactly what type of object they return if you're not sure.
Netilion usually only sends a minimal representation of an object (i.e. its ID) if an endpoint is called which is not the model's representation in Netilion; in such cases, one needs to figure out which is the appropriate endpoint to represent that model.
Units generally use the british spelling (metres_per_second, not meters_per_second)
Netilion (and thus this library) requires usage of the OAuth2 legacy password grant, where you exchange username and password of a virtual user for an access token.