Ardoqpy - a Python client for The Ardoq REST API

Description

Ardoqpy is a thin client library for the Ardoq REST API. It consists of 3 clients

• ArdoqClient
  • thin client for the rest-api
• ArdoqSyncClient
  • subclass of ArdoqClient
  • maintains a cache of aggregated workspace information
  • overrides write operations
    • only create components and references if they are not already in the cache
    • update cache for create and update operations
    • cache hit is based on
      • component: name, typeId
        • NB: name match is CASE_INSENSITIVE
      • reference: source, target, and type
  • overriders find_component (comp_name)
    • loads aggregated workspace to cache if its not present
    • finds component based on either of the following
      • name: substring or exact match
      • fieldname == fieldvalue (you need to ensure the types can handle equivalence)
        • fieldname, if not None, is checked first
  • can be run in simulate mode which updates the report but does not execute write operations in ardoq
• Ardoq V2 Client
  • this is a copy of the client provided by ardoq in their developer portal
  • v2 api functionality can be used from this client or built into the original ArdoqClient

Documentation

(see the test client for examples)

ArdoqClient Import Usage

from ardoqpy import ArdoqClient

ArdoqClient Implemented:

• workspace
  • get all
    • summary=True is undocumented in the REST docs but returns stats for workspaces
  • get by ID
  • get by ID aggregated
  • create workspace
  • delete
  • create folder
  • move workspace to folder
• component
  • get by ID
  • get all for workspace
  • create
  • delete
  • update
  • find by name in workspace
  • find by field_name / field_value in workspace
• reference
  • get all for workspace
  • get by ID
  • create
  • update
  • delete
• tag
  • get by ID
  • get all for workspace
  • create
  • update
  • delete
• model
  • get by ID
  • get all models and templates
  • print model to get IDs for component and reference types
  • find reference_type by name
  • find component_type by name
• folder
  • create
  • get by ID and all folders
• util
  • pprint
    • pretty print responses from ardoq calls

ArdoqSyncClient Import Usage

from ardoqpy_sync import ArdoqSyncClient
ardoq = ArdoqSyncClient(hosturl=host, token=token)
ardoqsim = ArdoqSyncClient(hosturl=host, token=token, simulate=True)

ArdoqSyncClient Implemented:

• all interfaces from ArdoqClient
• component
  • create
    • cache check is based on name attribute only (case insensitive)
  • update
• reference
  • create
    • cache check is based on source, target, and type attributes
  • update

Installation

pip install ardoqpy

Dependencies

• Python 3
• Requests - ardoqpy uses requests package for http requests

Quick Start

To get started, simply install ardoqpy, create an ArdoqClient object and call methods:

edit `ardoq.cfg` to include your API token
make sure `ardoqpy.py` opens your `ardoq.cfg`configuration file
use `testclient.py`as a basis for your own client

or from the console

from ardoqpy import ArdoqClient
ardoq = ardoqpy.ArdoqClient(hosturl='https://YOURORG.ardoq.com', token='YOURTOKEN')
# to use v2 API
ardoq = ardoqpy.ArdoqClient(hosturl='https://YOURORG.ardoq.com', token='YOURTOKEN', version='v2')
ardoq.get_workspaces()

Changelog

• 202401

  • add get reference for v2 client
  • added v2 api client. This is a copy of the one provided by ardoq on the developer portal

• 202307

  • added workspace and workspaces endpoints for v2 client

• 202307

  • added del and update tag

• 202303

  • added audit log for support for components created, updated, deleted, and skipped due to cache_hit

• 202211

  • added support for Ardoq v2 REST API. Only for the ArdoqClient (not SyncClient)

• 202207

  • add find_reference_type to return reftype definition from the metamodel for a workspace
  • add find_component_type to return comptype definition from the metamodel for a workspace. Checks full hierarchy

• 202204

  • add print_model to print component and reference IDs

• 20220228

  • add PR to include references in get_component function
  • fixed bug in ardoq_sync when logging ref without displayText

• 20220212

  • deprecated org parameter
  • removed problem with slash on url
  • change get all components in ws to search operation. In line with public API docs

• 20220131

  • fixed bug in SyncClient when searching for references in a WS without refs

• 20220122

  • changed get_model. calling without ws_id now returns all models
  • added get_folder. returns all folders if no folder_id

• 20211107

  • improve simulation mode
  • added cache_miss_comps and cache_miss_refs lists to capture items found in ardoq that are no longer in the source systems

• 20210717

  • Added simulate option to SyncClient to simulate write operations to update the report without modifying ardoq

• 20210420

  • Fixed PyPy support

• 20170125

  • Added pip and fields creation support.

• 20160618

  • bug and feature improvements
  • first version of the sync client

• 20160402

  • Initial dev

TODO

• complete the full REST-API for fields

License

The ardoq-python-client is licensed under the MIT License

See LICENSE.md