Ardoq offers a comprehensive REST-API as well as wrappers for selected programming languages. You can use the REST-API to integrate with Ardoq, for example, to automate documentation, or to create custom tools that make use of data from Ardoq.
Authorization is via an Ardoq API token. You can explore the API and interact with it using the generated Swagger API documentation. (Beware: The Swagger definitions currently do not support import into code generators etc.)
Log in to Ardoq and open the API documentation from the help menu:
Check out our REST API Tutorial for examples of using the API.
Native REST clients and Javadoc example
We have created native REST clients for:
ℹ️ This library is now deprecated in favour of our upcoming improved REST API. The API will be well-documented with accompanying OpenAPI specs. We encourage direct use of the REST API. Client-code can alternatively be generated from the OpenAPI specs.
You can also generate clients in many languages from the Swagger documentation, for example via Swagger Codegen.
We have also created a plugin that shows how you can automatically document Java Applications.
Principles and best practices
The Ardoq REST API is on purpose somewhat minimal. The main goal is to enable you to access and maintain your data as it is in Ardoq, without many "knobs" for fine-tuning what data you get. Ardoq acts as a relatively dumb data store and the client needs to do the heavy lifting. The benefit is that you are free to do things the way you want, without having to rely on Ardoq to have designed the API so that it fits exactly your particular use case (and needing to deal with all the mismatches). The following guidelines will make it easier for both you and Ardoq.
Decide who is the source of truth and only allow data changes there. Often it will be your system that is the source of truth, with data copied into Ardoq and presented there as read-only. If you make it possible to edit data in both systems then you are getting into a deep hole of managing conflicts.
Cache/keep data locally - your integration will be faster and possibly easier to write if you maintain a cache of important data such as mappings between your system's and Ardoq's IDs. If your system is the master then you can even persist this data. You can then keep the data in the form conductive to what you are doing instead of performing repeated lookups in the API that is ill-suited to your purpose.
Do not call the APIs more frequently than necessary as it puts unnecessary strain on our resources and your integration could fail due to rate limiting. If Ardoq is the source of truth then decide how outdated data you can tolerate, based on its importance and frequency of edits.
Support
❓Still have questions? Reach out to us via our website or by using the in-app chat.