This article refers to version 1 of our REST API. We now have a new API and you can find the API documentation on our newdeveloper portal. Version 1 is still available, but we recommend customers use the new API for all new integrations.
Note: Organizations with custom domains should use these and not app.ardoq.com
Ardoq offers a comprehensive REST API and wrappers for selected programming languages. You can use the REST API to integrate with Ardoq, for example to automate documentation or create custom tools that use data from Ardoq.
Normally we recommend that you use one of the REST API wrappers to access the API, but in this tutorial we want to be language independent and will use cURL (from the terminal) to illustrate the API requirements.
You will find it useful to become familiar with Ardoq concepts when you start working with the API, so be sure to check them out.Basic concepts of Ardoq.
Requirements:
An Ardoq account with read and write permissions.Contact Usif you do not have one
They areToken APIfor authorization.
For Windows if you want to follow the tutorialrice.
Useful Chrome Extensions
formateador JSONto make the api responses look pretty
Talent-API-Testerto explore the API in a convenient interface
(Alternatives to the above plugins should also be available in other browsers.)
Una API RESTful
Note that the API is RESTful and the various methods it exposes are described in the automatically generated Swagger API documentation. Log in to Ardoq and open the documentation from the Help menu.
The API GUI is interactive, so you can experiment using the API right there, or create a token and continue using other API clients as described above.
Also, you can read more about the semantics ofPOST, PUT, and DELETE requests.
If you follow this step-by-step tutorial, be sure to replace the API token with your own, and replace the IDs in the requests with the ones you get back from the API.
Danger!In a REST API, PUT requests to update a resource actually perform a "replace" operation, which means it must also include any previous values; otherwise they will be reset to their null values. To update a single field value, use the PATCH operation.
Pied Piper has developed a new search engine that is much more efficient than Google's. His strategy for gaining market share is to steal customers from Google through the clever use of an AdWords campaign.
The process can be schematized as follows:
Users search Google for a term that shows the ad.
The user clicks on the Pied Piper ad.
The user is redirected to one of five landing pages.
Ardoq comes with the tailored business process model template to document the above process:
It makes sense to group the process steps hierarchically under the unified business process component type so that we can document multiple processes in the same workspace.
Using the model, we can create the following structure for the Google Adwords process (business processes):
User searches Google for a campaign term (manual task)
User clicks Pied Piper ad (manual task)
The user is redirected to one of the five landing pages (automated task)
Since workspace structures are model-based, we first need to find the model ID of the business process model template.
Search all models
Consultation
curl \ -H "Accepts: application/json" \ -H "Authorization: Token token=suAPIToken" \ -X GET "https://app.ardoq.com/api/model"
caught:If you are logged in, you can also access the API directly from your browser. Here is theVista JSONThe extension is useful for printing the response nicely. You can also make inquiries through theDHC RESTlet clientsyou prefer a GUI.
Answer
[ { "name": "Proceso de negocio", "_id": "570294f572fa6d517c841811", ...andere Felder... },...]Creating the workspace
Using the model template_IDNow we can 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": "Kundengewinnung", "componentTemplate": "570294f572fa6d517c841811", "description": "" }'Answer
Here we want to remember the workspace_ID:
{ "description": "", "last update": "2016-04-05T09:35:12.077Z", "tags": [], "_id": "570386d072fa6d547578e072", ...andere Felder... }Creating our components
Of course, if we recall our component sketch, we would start with the top "AdWords Campaign" component (business processes).
User searches Google for a campaign term (manual task)
User clicks Pied Piper ad (manual task)
The user is redirected to one of the five landing pages (automated task)
Consultation
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-Kampagne", "rootWorkspace": "570386d072fa6d547578e072", "description": "" }'Answer
{ "description": "", "_order": 500.2, "last update": "2016-04-05T11:29:08.381Z", "_id": "5703a1849f2a264e83a8b0b9", "type": "Geschäftsprozess", " typeId ": "p1448628262462",... as well as Felder...}We would like to point this out again here_IDas our components below are children of the AdWords campaign component.
It's also worth noting that when we created the component, we didn't specify the typeId field. Since we only have one top-level component in our model, the API infers the type at creation time to the first available in the component's hierarchy level, so the AdWords campaign type is Business Process.
When we create a child component of the AdWords campaign, the type is inferred to an automated task. However, we want to create two manual tasks, so we need to find the type ID of the manual task by querying the model endpoint using the model ID we have available above.
Determining Type IDs of Component Types
curl\ -H "Content-Type: application/json"\ -H "Acepta: application/json"\ -H "Autorización: Token token=yourAPIToken"\ -X GET "https://app.ardoq.com/api /modelo/570294f572fa6d517c841811"
Answer
{ ...other fields... "root": { "p1448628262462": { "description": "A business process", "children": { "p1448628261966": { "description": "Automated task execution software ", "children": {}, "color": "", "index": 2, "canLinkTo": [ "p1448628261966", "p1448628260381" ], "name": "Automated Task", "icon": " laptop" , "default": {}, "level": 2, "return value": false, "id": "p1448628261966", "shape": "default process" }, "p1448628260381": { "description" : "Manual task that a person performs.", "children": {}, "color": "#5610B7", "index": 1, "canLinkTo": [ "p1448628260381", "p1448628261966" ], "name" :"manual task", "icon": "user", "default": {}, "level": 2, "return value": false, "id": "p1448628260381", "form": "process" } }, "index": 1, "canLinkTo": null, "name": "business process", "icon": "globe", "default": {}, "level": 1, "returnsValue": false , "id": " p1448628262462 ", "form": "process" } }, ...other fields...}
HerootThe attribute in the model response references the top-level component types in our model. As we can read in the previous answer, the manual task hasID de tipo: p1448628260381, while the automated task hasID de tipo: p1448628261966. Now we can create components for the later steps of our business process.
Petitions
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 ad", "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 searches Google for a campaign term", "typeId": "p1448628260381", "parent": "5703a1849f2a264e83a8b0b9", "rootWorkspace": "570386d072fa6d547578e072 ", " description": "" }'curl \ -H "Content-Type: application/json" \ -H "Accepted: application/json" \ -H "Authorization: Token token=yourAPIToken" \ -X POST "https : // app.ardoq.com/api/component" \ -d '{ "name": "User will be redirected to one of five landing pages", "typeId": "p1448628261966", "parent": " 5703a1849f2a264e83a8b0b9", " rootWorkspace ": "570386d072fa6d547578e072", "description": "" }'Answer
{ "_id": "5703c80f72fa6d547578f042", "name": "The user searches Google for a campaign term", ...other fields...}{ "_id": "5703c83372fa6d547578f044", "name": "The user clicks Pied Piper Ad", ...other fields...}{ "_id": "5703c8379f2a264e83a8b2cb", "name": "User will be redirected to one of five landing pages." ...other fields...}👀 When you open the workspace in theArdoq application, you should now have the following components in the browser:
references
It's clear that each step of the AdWords campaign process depends on the previous step. To make these dependencies visible, we need to create references between them.
However, to create the references, we need to set a reference type. To find this, similar to component types, we need to query the model to find a suitable one.
Find Reference Types
curl \ -H "Type of content: application/json" \ -H "Accepts: application/json" \ -H "Authorization: Token token=suAPIToken" \ -X GET "https://app.ardoq.com/api /model/570294f572fa6d517c841811"
Answer
{ ...andere Felder... "name": "Proceso de negocio", "referenceTypes": { "0": { "returnsValue": "false", "svgStyle": "stroke: blue;stroke-dasharray:2 ", "charLine": "=", "lineEnding": "bottom", "color": "blue", "line": "dotted", "id": 0, "name": "Hängt ab von" } , "1": { "returnsValue": "false", "svgStyle": "stroke: black;", "charLine": "-", "lineEnding": "both", "color": "black", " línea ": "sólido", "id": 1, "nombre": "Nächster Schritt" }, "2": { "nombre": "implícito", "id": 2, "línea": "discontinua", " 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: grey;", "charLine": " ? ", "lineEnding": "circle", "color": "gray", "line": "solid", "id": 4, "name": "Supports" } }, ...andere Felder.. . }Creating the references
As we can see from the answers above, our business process model has a "Next Step" reference type which is perfect for our use. So we want to use the id type1.
From our component responses we get the following IDs:
The user searches Google for a campaign term:
5703c80f72fa6d547578f042The user clicks on the Pied Piper ad:
5703c83372fa6d547578f044The user will be redirected to one of five landing pages:
5703c8379f2a264e83a8b2cb
Petitions
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", "destination": "5703c83372fa6d547578f044", "rootWorkspace": "570386d072fa6d547578e072", "type": 1 "description": "" }'curl \ -H " Inhaltstyp: application/json" \ -H "Access: application/json" \ -H "Autorisierung: Token token=yourAPIToken" \ -X POST "https://app.ardoq.com/api/reference" \ -d ' { "source": "5703c83372fa6d547578f044", "destination": "5703c8379f2a264e83a8b2cb", "rootWorkspace": "570386d072fa6d547578e072", "type": 1 "description": "" }'If we go back to the app and open the lanes view (you may need to open it by clicking the "More" button).
We should see that the components are now connected. ⛓
component identification
Pied Piper thinks some of your processes are outdated and wants to review them. To do this in Ardoq, they want to tag all components scheduled for review with the "needs_review" tag so that they can then easily filter their data and start reviewing processes.
Let's take a look at the tagging API and tag the AdWords campaign for verification.
creating a label
Consultation
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_fix", "workspace root": "570386d072fa6d547578e072", "description": "" }'Answer
{ "description": "", "last update": "2016-04-06T10:28:01.487Z", "_id": "5704e4b19f2a26556d1976a7", "lastModifiedByName": "Richard", "name": "needs_review" , "created by email": "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"}highlight a component
caught:We could have tagged the component when we created the tag by passing an array of components with the id of the components we want to tag, but as a demonstration, let's send another request to update the tag.
Remember that the component ID is AdWords Campaign5703a1849f2a264e83a8b0b9Since we are updating the resource with a PUT request, we must include the entire resource.
Consultation
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", "last modified by name": "Richard ", "name": "needs_review", "createdByEmail": "richard@piedpiper.com", "created": "2016-04-06T10:28:01.487Z", "rootWorkspace": "570386d072fa6d547578e072", " created- by": "570294f472fa6d517c841810", "last modified by": "570294f472fa6d517c841810", "last modified by email": "richard@piedpiper.com", "_version": 1, "createdByName": "Richard", "components": [ "5703a1849f2a264e83a8b0b9"] }'creating a field
Finally, Pied Piper wants to have an overview of who is responsible for each process, so he wants to add a maintainer field to the business process component type in the model.
Remember the ID of the business process type:p1448628262462, and our model:570294f572fa6d517c841811.
Consultation
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": "", "component type": ["p1448628262462"] , " Type": "Email" }'Set the field value of a component
Erlich Bachman is the company's Google guru, so we'd like to update the Google Adwords Campaign Supervisor field to point to his email address.erlich.bachman@aviato.com
caught:Fields are created in the model, but to set a field in a component, update the component directly. As a result, the fields are added as custom fields to the component payload during initialization.
Again, since we're updating the component, we need to include the entire resource. Normally we would handle this on our client using a library that implements the RESTful endpoints and stores the intermediate models. 🍀 Fortunately, we save the response from our previous component if you don't try to get it via a component API request.
Consultation
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 update": "2016-04-05T11:29:08.381Z", "_id": "5703a1849f2a264e83a8b0b9", " Kinder": [ "5703c80f72fa6d547578f042", "5703c83372fa6d547578f044", "5703c8379f2a264e83a8b2cb" ], "Elternteil": null, "lastModifiedByName": "Richard", "name": "AdWords"kampagne.com", "created@kampagne.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 its documentation. One idea might be to add a "Number" field to document the cost of each step in the business process. Try it yourself!
Advance
Great, you have completed the introduction to our REST API. Feel free to spend a little more time exploring the different endpoints or trying any of the ones available.API wrapper.
Stay tuned for more tutorials on using the Ardoq API. We'll soon see how we can create an API wrapper in the language of our choice (JavaScript/Node.JS) and try to document the Ardoq front-end application automatically.
Bonus: demo video
Below is a video showing some of the endpoints in the API. It also shows collaboration capabilities, which means that the Ardoq user interface is updated immediately on API events.
If you still have questions or need more information, please contact us via our website or in-app chat. 💬 After all, that's what we're here for.