1. Knowledge Base
  2. REST-API
  3. Getting Started
  4. REST API Tutorial

REST API Tutorial

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, read more about them here.

Prerequisites

  • An Ardoq account with read and write permissions. Signup for a free plan if you don’t have one.
  • Your API token for authorization.
  • For Windows, if you wish to follow the tutorial using cURL (download)

Helpful Chrome Extensions

  • JSON Formatter to make the API responses look pretty
  • DHC RESTlet 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 documentation, you can read more about the semantics of the POST, PUT and DELETE requests here.

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.

Gotcha: 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. PATCH requests are not available in the Ardoq API.

Our Case

Pied Piper have 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 clever use of an AdWords campaign.

The process can be outlined like this:

  1. User googles for a term which shows the advertisement.
  2. User clicks the Pied Piper advertisement.
  3. User is re-directed 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:

  • AdWords Campaign (Business Process)

    1. User googles a term in the campaign (Manual Task)
    2. User clicks the Pied Piper advertisement (Manual Task)
    3. User is re-directed to one of five landing pages (Automated Task)


Creating the ‘Customer Acquisition’ Workspace

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

Finding the model ID

Request

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

Creating the workspace (Workspace API)

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

Response

Here we want to make note of the workspace _id:

Creating our Components (Component API)

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

  • AdWords Campaign (Business Process)

    1. User googles a term in the campaign (Manual Task)
    2. User clicks the Pied Piper advertisement (Manual Task)
    3. User is re-directed to one of five landing pages (Automated Task)


Request

Response

Again, we want to take note of the _idfield, 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’.

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

Response

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

Responses

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

References (Reference API)

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 the 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

Response

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 re-directed to one of the five landing pages:5703c8379f2a264e83a8b2cb

Requests

If we go back to the app and open the Swimlane view (you might have to open it by clicking the ‘+’-icon next to the Pages visualization).

We can see that the components are now linked together!

Tagging components (Tag API)

Pied Piper believe that some of their 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

Response

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 resouce with a PUT request, we have to include the whole resource.

Request

Creating a field (Field API)

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

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 which 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

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 to explore 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!

Was this article helpful?