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
-
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
-
20170125
- Added pip and fields creation support.
-
20160618
- bug and feature improvements
- first version of the sync client
-
20160402
TODO
- complete the full REST-API for fields
License
The ardoq-python-client is licensed under the MIT License
See LICENSE.md