Getting Started

echo-baze is an API wrapper used to easily interact with Bazefield within Python. It was completely rewritten in version 2.0 to allow for much easier and concise usability. Now all the methods are contained in a single class called Baze and the user only needs to import this class to use the functionalities of the package.

A lot of the code implemented here is based on the approach used by the Python Reddit API Wrapper PRAW. It's a very good example of how to implement an API wrapper in Python and it's recommended to take a look at it if you want to understand how this package works.

Usage

To interact with Bazefield using echo-baze you just need to create an instance of the Baze class. It can be instantiated in many ways depending on how you would like to authenticate. Below there are a couple examples.

from echo_baze import Baze
# using standard API key
baze = Baze()
# using custom API key
baze = Baze(api_key="<custom-API-key>")
# using user and password
baze = Baze(user="<user>", password="<password>", api_key=None)

Note

As API key is always the preferred login type, to use user and password login you must set argument api_key to None.

Structure

The Baze class is the only top level class in the package. It holds objects that make it easy to segregate usability of the different functionalities of the Bazefield API. The structure of the class is shown below.

Baze
├───Objects
│  └───Categories
│  └───Types
│  │  └───Attributes
│  │     └───Values
│  └───Models
│  │  └───Attributes
│  │     └───Definitions
│  │     └───Values
│  └───Instances
│     └───Attributes
│        └───Definitions
│        └───Values
├───Alarms
│  └───Definitions
│  └───History
├───Allocations
│  └───Types
│  └───Categories
│  └───History
│  └───Comments
│  └───Labels
├───Points
│   └───Templates
│   └───Definitions
│   └───Details
│   └───Tags
│   └───Values
│      └───Latest
│      └───Series
├───Curves
├───KPIs
│  └───Availability
│  └───TrackerAvailability
├───Devices
├───Roles
├───Users
├───Emails
├───Jobs
│  └───Recalc
│  └───RealarmReallocate
└───Links
   └───AlarmLog
   └───Availability
   └───Trend
   └───ObjectDash

Each object below Baze is an instance of it's own specific class, but all inherit from the base class BazeRoot. This class contains the methods that are common to all objects, and specially, defines the constructor that should not be overridden in the child classes. The constructor is responsible instantiating common attributes to all objects, such as the connection handler to the Bazefield API.

General Guidelines

• Key naming: The package maintains the same names used in Bazefield for consistency. This means that the keys used for data inserts and returns will match the keys used in Bazefield APIs, even if they are not the most readable names.
• Default keys: Methods that return values such as dicts or DataFrames will always use the names of the objects as keys/index. This is done to make it easier to use the returned values in other methods. The ids of those objects will be returned in the dict values or DataFrame columns as they are of secondary usage.

Common Methods

Note

Most of the classes will have at least some of the methods below to interact with the API. Regardless of that, it's important to note that most of the classes will just have some of them, as they are not all applicable to all classes.

• get_ids

  Method used to list all instances of the desired class. For example, if baze.objects.types.get_ids() is called all the possible object types would be returned.

  For consistency, it's expected that all get_ids methods return a dict containing the names as keys and the ids as values.

• get

  Method used to get the values of the desired class. For example, if baze.objects.types.get() is called all the possible objects would be returned, but this would include getting more data related to it than just the ids and names. This way this method can be seen as an extension of the get_ids method.

  As the return value of this can vary depending on the considered class, it's expected that all get methods have an argument called output_type to define what is the format of the output (a dict or a DataFrame for example). When output_type is set to DataFrame, in most cases, the pd.json_normalize method will be used to convert nested dicts to columns. This means that if the data returned by the API has sublevels, until the first level the data will be converted to columns with the names like level0.level1. This is done to make it easier to use the returned values in other methods.

• insert

  Method used to insert a new instance of the desired class. For example, if baze.objects.types.insert() is called a new object type would be created in Bazefield.

  In most cases it should have an argument called on_conflict to define how conflicts are handled. It's possible values will be:

  • raise: Raises an exception and is the default value.
  • ignore: Ignores the error and continues with the execution.
  • update: Updates the existing instance with the new values (only applicable in some cases like the insert method).

• update

  Method used to update an existing instance of the desired class. For example, if baze.objects.types.update() is called an existing object type would be updated in Bazefield.

• delete

  Method used to delete an existing instance of the desired class. For example, if baze.objects.types.delete() is called an existing object type would be deleted in Bazefield.

• export_file

  Method used to export the data of the desired class. For example, if baze.objects.types.export_file() is called all the object types would be exported to the desired file type.

  This method should have an argument called file_type to define what is the format of the output (a csv or an excel file for example).

• import_file

  Method used to import data of the desired class. For example, if baze.objects.types.import_file() is called all the object types would be imported from the desired file type.

Reference

As an API wrapper, it's recommend to check the documentation on the Bazefield API itself for further information. It is the base of most of the implementation on this package. Below are the main places where you can find more information on that:

• Bazefield Services
• Swagger

If you have trouble accessing any of the above try logging out and in of Bazefield and then accessing the page again. This usually solves most of the errors.

Bazefield Website Debugging

Some of the APIs listed above have very poor documentation. This way, a very good approach to understand how they work is to go to the Bazefield portal, find a page that uses the API and then open the Network tab on the browser developer tools (F12) to see the requests that are being made. This usually gives a very good insight on how to use the API