# Ardoqpy - a Python client for The Ardoq REST API
## Description
Ardoqpy is a thin client library for the [Ardoq](https://ardoq.com) REST API.
It consists of 2 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
## 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
- 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](https://github.com/kennethreitz/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
- 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 and tags
## License
The ardoq-python-client is licensed under the MIT License
See LICENSE.md