This article refers to version 1 of our REST API. We now have a new API and you can view the API documentation in our new Developer Portal. Version 1 is still available, but we encourage customers to use the new API for any new integrations.

Note: Organizations with custom domains must use that and not app.ardoq.com

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.

Normally we would advise you to use one of the REST-API wrappers to access the API, but in this tutorial, we wish to be language-agnostic and will use cURL (from the terminal) to illustrate the API requests.

You’ll find it helpful to be familiar with the concepts within Ardoq if you start working with the API, so make sure to check out the Ardoq fundamentals.

Prerequisites:

An Ardoq account with read and write permissions. Contact us if you don’t have one.
Your API token for authorization.
For Windows, if you wish to follow the tutorial using cURL.

Helpful Chrome Extensions

JSON Formatter to make the API responses look pretty
Talent API Tester to explore the API in a convenient interface
(Alternatives to the plugins above should be available in other browsers as well.)

A RESTful API

Make note that the API is RESTful and while the various methods it provides are outlined in the autogenerated Swagger API documentation. Log in to Ardoq and open the documentation from the help menu.

The API GUI is interactive, so you can experiment with using the API directly there, or you can create a token and continue with other API clients as explained above.

In addition, you can read more about the semantics of the POST, PUT and DELETE requests.

If you are following this tutorial step-by-step, make sure to replace the API Token with your own and replace the IDs in the requests with the ones you receive as a response from the API.

NB! In a REST API, the PUT requests to update a resource actually perform a “replace” operation, which means that you need to include all the previous values as well, otherwise they will be reset to their null values. In order to update a single field value, use the PATCH operation.

Tutorial Case

Pied Piper has developed a new search engine, which is far more efficient than Google’s. Their strategy to obtain market share is to steal Google’s customers through the clever use of an AdWords campaign.

The process can be outlined like this:

User Googles for a term that shows the advertisement.
User clicks the Pied Piper advertisement.
User is redirected to one of five landing pages.

Ardoq comes with the Business Process model template, which is tailored to document the process above:

It makes sense to group the steps of the process hierarchically under the unified ‘Business Process’ component type so that we can document several processes in the same workspace.

Using the model, we can come up with the following structure for the Google Adwords process (Business Process):

User googles a term in the campaign (Manual Task)
User clicks the Pied Piper advertisement (Manual Task)
User is redirected to one of five landing pages (Automated Task)

Creating the ‘Customer Acquisition’ Workspace

Since workspaces’ structures are based on models, we must first find the model ID of the Business Process model template.

Finding all the models

Request

curl \
  -H "Accepts: application/json" \
  -H "Authorization: Token token=yourAPIToken" \
  -X GET "https://app.ardoq.com/api/model"

Gotcha: if you are logged in, you can also access the API directly through your browser. This is where the JSON View extension comes in handy to pretty-print the response. You can also make the requests using the DHC RESTlet Client if you prefer a GUI.

Response

[
  {
    "name": "Business Process", 
    "_id": "570294f572fa6d517c841811",
    ...other fields...
  },
...]

Creating the workspace

Using the model template _id field, we can now create our workspace.

curl \
  -H "Content-Type: application/json" \
  -H "Accepts: application/json" \
  -H "Authorization: Token token=yourAPIToken" \
  -X POST "https://app.ardoq.com/api/workspace" \
  -d '{ 
          "name": "Customer Acquisition", 
          "componentTemplate": "570294f572fa6d517c841811", 
          "description": "" 
       }'

Response

Here we want to make note of the workspace _id:

{
  "description": "",
  "last-updated": "2016-04-05T09:35:12.077Z",
  "tags": [],
  "_id": "570386d072fa6d547578e072",
  ...other fields...
}

Creating our Components

If we recall our component outline, we would naturally start with the top-level component ‘AdWords Campaign’ (Business Process).

User googles a term in the campaign (Manual Task)
User clicks the Pied Piper advertisement (Manual Task)
User is redirected to one of five landing pages (Automated Task)

Request

curl \
  -H "Content-Type: application/json" \
  -H "Accepts: application/json" \
  -H "Authorization: Token token=yourAPIToken" \
  -X POST "https://app.ardoq.com/api/component" \
  -d '{ 
          "name": "AdWords Campaign", 
          "rootWorkspace": "570386d072fa6d547578e072", 
          "description": ""
       }'

Response

{
  "description": "",
  "_order": 500.2,
  "last-updated": "2016-04-05T11:29:08.381Z",
  "_id": "5703a1849f2a264e83a8b0b9",
  "type": "Business process",
  "typeId": "p1448628262462",
 ...other fields...
}

Again, we want to take note of the _id field since our subsequent components will be children of the AdWords campaign component.

It is also worth noting that we didn’t specify the typeId field when creating the component. Since we only have one top-level component in our model, the API will infer the type upon creation to the first one available at the hierarchical level of the component hence the AdWords Campaign is of Type ‘Business Process’.

REST API Tutorial, Ardoq business process

If we create a child component of the Adwords Campaign, the type will be inferred to an Automated Task, however, we wish to create two manual tasks so we have to find the type ID of the manual task by querying the Model endpoint using the model ID we have available from earlier.

Finding the type IDs of the Component Types

curl\
  -H "Content-Type: application/json"\
  -H "Accepts: application/json"\
  -H "Authorization: Token token=yourAPIToken"\
  -X GET "https://app.ardoq.com/api/model/570294f572fa6d517c841811"

Response

{
  ...other fields...
  "root": {
    "p1448628262462": {
      "description": "A business process",
      "children": {
        "p1448628261966": {
          "description": "Automated task that software performs",
          "children": {},
          "color": "",
          "index": 2,
          "canLinkTo": [
            "p1448628261966",
            "p1448628260381"
          ],
          "name": "Automated task",
          "icon": "laptop",
          "defaults": {},
          "level": 2,
          "returnsValue": false,
          "id": "p1448628261966",
          "shape": "predefinedProcess"
        },
        "p1448628260381": {
          "description": "Manual task that a person performs.",
          "children": {},
          "color": "#5610B7",
          "index": 1,
          "canLinkTo": [
            "p1448628260381",
            "p1448628261966"
          ],
          "name": "Manual task",
          "icon": "user",
          "defaults": {},
          "level": 2,
          "returnsValue": false,
          "id": "p1448628260381",
          "shape": "process"
        }
      },
      "index": 1,
      "canLinkTo": null,
      "name": "Business process",
      "icon": "globe",
      "defaults": {},
      "level": 1,
      "returnsValue": false,
      "id": "p1448628262462",
      "shape": "process"
    }
  },
  ...other fields...
}

The root attribute in the model response points to the top-level component types in our model. As we can read from the response above, the Manual task has typeId: p1448628260381, while the Automated Task has typeId: p1448628261966. Now we can create components for the subsequent steps in our business process.

Requests

curl \
  -H "Content-Type: application/json"\
  -H "Accepts: application/json"\
  -H "Authorization: Token token=yourAPIToken"\
  -X POST "https://app.ardoq.com/api/component"\
  -d '{ 
          "name": "User clicks the Pied Piper advertisement", 
          "typeId": "p1448628260381", 
          "parent": "5703a1849f2a264e83a8b0b9",
          "rootWorkspace": "570386d072fa6d547578e072",
          "description": ""
       }'
 
curl \
  -H "Content-Type: application/json" \
  -H "Accepts: application/json" \
  -H "Authorization: Token token=yourAPIToken" \
  -X POST "https://app.ardoq.com/api/component" \
  -d '{ 
          "name": "User googles a term in the campaign", 
          "typeId": "p1448628260381", 
          "parent": "5703a1849f2a264e83a8b0b9",
          "rootWorkspace": "570386d072fa6d547578e072",
          "description": ""
       }'
 
curl \
  -H "Content-Type: application/json" \
  -H "Accepts: application/json" \
  -H "Authorization: Token token=yourAPIToken" \
  -X POST "https://app.ardoq.com/api/component" \
  -d '{ 
          "name": "User is re-directed to one of five landing pages", 
          "typeId": "p1448628261966", 
          "parent": "5703a1849f2a264e83a8b0b9",
          "rootWorkspace": "570386d072fa6d547578e072",
          "description": ""
       }'

Responses

{
  "_id": "5703c80f72fa6d547578f042",
  "name": "User googles a term in the campaign",
  ...other fields...
}
 
{
  "_id": "5703c83372fa6d547578f044",
  "name": "User clicks the Pied Piper advertisement",
  ...other fields...
}
 
{
  "_id": "5703c8379f2a264e83a8b2cb",
  "name": "User is re-directed to one of five landing pages."
  ...other fields...
}

👀 If you open the workspace in the Ardoq app, you should now have the following components in the navigator:

References

It is clear that each step in the AdWords Campaign process is dependent on the previous step. In order to visualize these dependencies, we must create references between them.

However, in order to create the references, we must set a reference type. In order to find this, similar to component types, we must query the model to find an appropriate one.

Finding the reference types

curl \
  -H "Content-Type: application/json" \
  -H "Accepts: application/json" \
  -H "Authorization: Token token=yourAPIToken" \
  -X GET "https://app.ardoq.com/api/model/570294f572fa6d517c841811"

Response

{
  ...other fields...
  "name": "Business Process",
  "referenceTypes": {
    "0": {
      "returnsValue": "false",
      "svgStyle": "stroke: blue;stroke-dasharray:2",
      "charLine": "=",
      "lineEnding": "bottom",
      "color": "blue",
      "line": "dotted",
      "id": 0,
      "name": "Depends on"
    },
    "1": {
      "returnsValue": "false",
      "svgStyle": "stroke: black;",
      "charLine": "-",
      "lineEnding": "both",
      "color": "black",
      "line": "solid",
      "id": 1,
      "name": "Next Step"
    },
    "2": {
      "name": "Implicit",
      "id": 2,
      "line": "dashed",
      "color": "red",
      "lineEnding": "bothFilled",
      "returnsValue": false,
      "charLine": "_",
      "svgStyle": "stroke: red;stroke-dasharray:10,5"
    },
    "3": {
      "returnsValue": false,
      "svgStyle": "stroke: orange;stroke-dasharray:2",
      "charLine": "+",
      "lineEnding": "both",
      "color": "orange",
      "line": "dotted",
      "id": 3,
      "name": "Uses"
    },
    "4": {
      "returnsValue": false,
      "svgStyle": "stroke: gray;",
      "charLine": "?",
      "lineEnding": "circle",
      "color": "gray",
      "line": "solid",
      "id": 4,
      "name": "Supports"
    }
  },
  ...other fields...
}

Creating the References

As we can see from the responses above, our Business Process model has a “Next Step” reference type which is perfect for our use. Hence, we want to use the type ID 1.

From our Component responses, we obtain the following IDs:

User googles a term in the campaign:5703c80f72fa6d547578f042
User clicks the Pied Piper advertisement:5703c83372fa6d547578f044
User is redirected to one of the five landing pages:5703c8379f2a264e83a8b2cb

Requests

curl \
  -H "Content-Type: application/json" \
  -H "Accepts: application/json" \
  -H "Authorization: Token token=yourAPIToken" \
  -X POST "https://app.ardoq.com/api/reference" \
  -d '{ 
          "source": "5703c80f72fa6d547578f042", 
          "target": "5703c83372fa6d547578f044",
          "rootWorkspace": "570386d072fa6d547578e072",
          "type": 1
          "description": ""
       }'
 
curl \
  -H "Content-Type: application/json" \
  -H "Accepts: application/json" \
  -H "Authorization: Token token=yourAPIToken" \
  -X POST "https://app.ardoq.com/api/reference" \
  -d '{ 
          "source": "5703c83372fa6d547578f044", 
          "target": "5703c8379f2a264e83a8b2cb",
          "rootWorkspace": "570386d072fa6d547578e072",
          "type": 1
          "description": ""
       }'     }'

If we go back to the app and open the Swimlane view (you might have to open it by clicking the "More" button.

We should see that the components are now linked together. ⛓

Tagging components

Pied Piper believes that some of its processes are outdated and would like to review them. In order to do that in Ardoq, they wish to tag all the components up for review with the “needs_review tag”, so that they can later easily filter their data and start reviewing the processes.

Let’s have a look at the tagging API and tag the AdWords Campaign for review.

Creating a tag

Request

curl \
  -H "Content-Type: application/json" \
  -H "Accepts: application/json" \
  -H "Authorization: Token token=yourAPIToken" \
  -X POST "https://app.ardoq.com/api/tag" \
  -d '{ 
          "name": "needs_review", 
          "rootWorkspace": "570386d072fa6d547578e072",
          "description": ""
       }'

Response

{
  "description": "",
  "last-updated": "2016-04-06T10:28:01.487Z",
  "_id": "5704e4b19f2a26556d1976a7",
  "lastModifiedByName": "Richard",
  "name": "needs_review",
  "createdByEmail": "richard@piedpiper.com",
  "created": "2016-04-06T10:28:01.487Z",
  "rootWorkspace": "570386d072fa6d547578e072",
  "created-by": "570294f472fa6d517c841810",
  "last-modified-by": "570294f472fa6d517c841810",
  "lastModifiedByEmail": "richard@piedpiper.com",
  "_version": 1,
  "createdByName": "Richard"
}

Tagging a Component

Gotcha: we could have tagged the component upon creation of the tag by passing along a components array with the ID of the components we wish to tag, but for illustration, we send another request to update the tag.

Recall that the ID of the ‘AdWords Campaign’ component is 5703a1849f2a264e83a8b0b9 Since we are updating the resource with a PUT request, we have to include the whole resource.

Request

curl \
  -H "Content-Type: application/json" \
  -H "Accepts: application/json" \
  -H "Authorization: Token token=yourAPIToken" \
  -X PUT "https://app.ardoq.com/api/tag/5704e4b19f2a26556d1976a7" \
  -d '{
        "description": "",
        "last-updated": "2016-04-06T10:28:01.487Z",
        "_id": "5704e4b19f2a26556d1976a7",
        "lastModifiedByName": "Richard",
        "name": "needs_review",
        "createdByEmail": "richard@piedpiper.com",
        "created": "2016-04-06T10:28:01.487Z",
        "rootWorkspace": "570386d072fa6d547578e072",
        "created-by": "570294f472fa6d517c841810",
        "last-modified-by": "570294f472fa6d517c841810",
        "lastModifiedByEmail": "richard@piedpiper.com",
        "_version": 1,
        "createdByName": "Richard",
        "components": ["5703a1849f2a264e83a8b0b9"]
      }'

Creating a field

Finally, Pied Piper wants to have an overview of who has the responsibility for each process, hence they want to add a maintainer field to the Business Process component type in the model.

Let’s recall the type ID of the Business Process: p1448628262462, and our model: 570294f572fa6d517c841811.

Request

curl \
  -H "Content-Type: application/json" \
  -H "Accepts: application/json" \
  -H "Authorization: Token token=yourAPIToken" \
  -X POST "https://app.ardoq.com/api/field" \
  -d '{ 
          "name": "maintainer", 
          "label": "Maintainer",
          "model": "570294f572fa6d517c841811",
          "description": "",
          "componentType": ["p1448628262462"],
          "type": "email"
       }'

Setting the field value of a component

Erlich Bachman is the company’s Google guru, so we want to update the maintainer field of the Google Adwords campaign to point to his e-mail address erlich.bachman@aviato.com

Gotcha: Fields are created on the model, but to set a field on a component, you update the component directly. As a result, fields will be added to the component’s payload as a custom field upon initialization.

Again, since we are updating the component, we must include the whole resource. Normally we would handle this in our client by using a library that implements the RESTful endpoints and saves the intermediate models. 🍀 Luckily, we have our component response saved from before, if you don’t try GETting it by issuing a request to the component API.

Request

curl \
  -H "Content-Type: application/json" \
  -H "Accepts: application/json" \
  -H "Authorization: Token token=yourAPIToken" \
  -X PUT "https://app.ardoq.com/api/component/5703a1849f2a264e83a8b0b9" \
  -d '{
        "description": "",
        "_order": 500.2,
        "last-updated": "2016-04-05T11:29:08.381Z",
        "_id": "5703a1849f2a264e83a8b0b9",
        "children": [
          "5703c80f72fa6d547578f042",
          "5703c83372fa6d547578f044",
          "5703c8379f2a264e83a8b2cb"
        ],
        "parent": null,
        "lastModifiedByName": "Richard",
        "name": "AdWords Campaign",
        "createdByEmail": "richard@piedpiper.com",
        "type": "Business process",
        "created": "2016-04-05T11:29:08.381Z",
        "rootWorkspace": "570386d072fa6d547578e072",
        "state": "new",
        "typeId": "p1448628262462",
        "isPublic": false,
        "created-by": "570294f472fa6d517c841810",
        "last-modified-by": "570294f472fa6d517c841810",
        "lastModifiedByEmail": "richard@piedpiper.com",
        "component-key": "CUA-1",
        "version": "0.0.1",
        "_version": 1,
        "createdByName": "Richard",
        "model": "570294f572fa6d517c841811",
        "maintainer": "erlich.bachman@aviato.com"
      }'

Pied Piper could easily add more fields to enrich their documentation. One idea could be to add a “Number” field to document the cost of each step in the business process. Go ahead and try it out yourself!

Moving Forward

Awesome, you have completed the introduction to our REST API! Feel free to spend some more time exploring the various endpoints or try out one of the available API wrappers.

Stay tuned for more tutorials on using the Ardoq API. Soon we will be looking at how we can create an API wrapper in our language of choice (JavaScript/Node.JS) and have a go at automatically documenting the Ardoq Front-End application!

Bonus: Demo Video

Below is a video demoing some of the endpoints in the API. It also shows the collaboration capabilities, meaning the Ardoq UI immediately gets updated on API events.

If you still have questions or need more information, reach out to us via our website or by using the in-app chat. 💬 After all, that's what we're here for.

Automating Swagger Documentation with Jenkins

Ardoq REST API