Admin system REST API
- Håkon Clausen
- Kristian Jacobsen (Unlicensed)
- Åsmund Johansen
This document documents the possibility of interfacing with the admin system using REST calls (GET, POST, PUT, PATCH, DELETE), allowing the automation of tasks like creating projects and users.
All examples are produced using the curl utility.
General
Authentication
The system uses BASIC AUTH authentication. Logging in simply needs an admin system user, and you can log in with the same username and password combination you use for regular WEB access.
Data formats and URLs
All resources can be accessed using HTML, XML, or JSON formats.
This is a separate API from the normal REST API, and the base URL should be the same as the admin system (e.g., https://adm-us.drofus.com/) you are trying to access.
For the link, http://[admin-url]/projects give the regular HTML project listing while http://[admin-url]/projects.json gives the list with project and project users in JSON format(
Some resources (notable users) have dots (.) in their resource names, so the .json can not be used. Be sure to send "Accept: application/json" in the header instead so (This applies to all types of clients(e.g., postman, etc.). ,
Setting the Accept header to "application/JSON" is the recommended way of getting responses in JSON format. .json should only be used when testing
curl -H "Accept: application/json" -s -u testadmin:testpw http://[admin-url]/users/hakonhcwill give the same as
curl -s -u testadmin:testpw http://[admin-url]/users/hakonhc.jsonResources:
Resource | Description |
|---|---|
/projects | Lists and manipulation of projects |
/owners | Listing of project owners |
/users | Listing and manipulation of users on the server |
/database | Listing and manipulation of databases |
/project_users | Listing and manipulation of users in projects |
Most resources responds to both GET, PATCH, and DELETE
In addition, we have some unique endpoints for:
Resource | METHOD | Description |
|---|---|---|
/node/logins | GET | Get login statistics for projects over the last five years, grouped by type of client used(Revit, dRofus, etc.). |
/node/logins?from_date=2018-01-01&to_date=2019-12-31 | GET | Get login statistics for projects for the given period, grouped by type of client used(Revit, dRofus, etc.) |
/node/unique_users | GET | Gets the number of unique users for each project for the last 5 years |
/node/unique_users?from_date=2018-01-01&to_date=2019-12-31 | GET | Gets the number of unique users for each project for the given time period. |
/project_data?from_date=2018-01-01&to_date=2019-12-31 | GET | Get statistics values on projects, to_date and from_date are optional limits on date |
/password/request_reset | GET | A post request with a valid username will trigger a password reset email |
/password/reset | GET | Use this with a token to change the password with the API |
/owners/[id]/tasks/[TaskName]/run?source=[sourcedb]©_ids=[ids] | POST | Run a given task against all databases for a given owner. TaskName is one of the following
|
GET Resources: Listings
Resource | Description | Parameters |
|---|---|---|
/projects | List all projects | ?query=xx will list all projects containing xx in the name ?show_all=1 to also include inactive projects |
/projects/1 | List project with id 1 |
|
/owners | List all owners |
|
/owners/1 | List owner with ID 1 |
|
/users | List of all users | ?query=xx to search |
/users/username | List user with username |
|
/database | List databases |
|
/project_users/username,projectid | Show project user |
|
Example
$ curl -s -u testadmin:testpw http://[admin-url]/projects.json?query=template|json_reformat
[
{
"project": {
"active": true,
"contact": null,
"created_at": "2016-11-01T09:39:14Z",
"created_by": null,
"database_id": "akl-test",
"description": null,
"gross_area": null,
"id": 399,
"name": "dRofus dev template",
"no": "01",
"owner_id": 5,
"status": null,
"updated": null,
"updated_by": null,
"unit_type": "SM" #SM for square meters or SF for square feet
}
},
.....POST Resources: Creating objects
Example
This creates an owner with the name "Test," and from the return, we can see that it has been assigned with ID 11
Creating a new project ( POST /projects)
Creating a new project requires some special parameters. This would be the minimal data to provide when creating a new project
Parameter | Description |
|---|---|
new_db | 1 to create a new database or 0 to add a project to an existing database |
new_db_template | If creating a new database, provide the database name that would be used as a template |
new_db_name | If creating a new database, provide the name of the new database |
existing_db_name | If NOT creating a new database (new_db set to 0), provide the name of the existing database to add the new project to |
name | Name of the project |
constructor | Name of the constructor/firm of the new project |
description | Description of the project |
owner_id | The ID of the owner |
project_type_id | Type of project. Use one of the following values.
id │ name
|
All the parameters are mandatory.
Example
Creating a new project user (POST /project_users)
Where data.json contains
Parameter | Description |
|---|---|
project_user | project_id: ID of the project to add to room_rights: room permission level equipment_rights tender_rights consignation_rights system_rights modelstore_rights superuser. Project Administrator addon_admin: BIM admin no_web_admin_access: if a user is a superuser, this denies access to the web admin hide_price: true or false should the user see prices |
user | username: Username of the user to add first_name: First name of the user to add last_name: Last name of the user to add email: Email of the user to add If the user exists, make sure that the information given is equal to the information registered on the server |
mail_type | ID of the email to send to the user (from /emails), "skip_email" means no email will be sent. |
GET Resources: Object manipulation and more
Databases
Resource |
|
|---|---|
/database/[dbname]/disableall | Disables all project users in the database with the name dbname |
/database/[dbname]/enableall | Enables all project users in the database with the name dbname |
/database/[dbname]/kickall | Logs out all users in the database with name dbname |
/database/[dbname]/get_backup_now | Downloads a backup of the database |
Users
Resource |
|
|---|---|
/users/[username]/disable | Disables users so they can not log into any project |
/users/[username]/enable | Enables a user |
/users/[username]/kick | Logs out all users in database xxx |
POST Resources: Toggles and other changes
Users
Resource |
|
|---|---|
/users/[username]/toggle_otp | Toggles whether the user has to login using Multi-Factor Authentication |
/users/[username]/toggle_force_weblogin | Toggles whether the user has to login using Modern Login/SSO |
/users/[username]/toggle_local_authentication | Toggles whether the user can use local or have to use external authentication (Entra) |
/users/[username]/toggle_enable | Toggles enabling and disabling the user |
/users/[username]/merge?to=[to_username] | Merge user into another user |
PUT/PATCH Resources: Updates
Resource |
|
|---|---|
/projects/[id] | Update project |
/project_users/username,projectid | Update project user |
Example 1: Update project
Where data.json contains
Example 2: Update project user
Where data.json contains
DELETE Resources
You also use the DELETE operation to delete most objects.
This example will delete a user in a project
Resetting Password
Posting a JSON request to "/password/request_reset" with this body and a correct username will start the reset password process. The user will get a password reset request via email with a token:
To change the password use the following JSON with the token from the email:
Project Statistics
Resource | Comment |
|---|---|
/project_data | Gives project statistics over time |
/project_data/latest | It gives you the latest project statistics for each project |
Filters
|
|
|---|---|
from_date=[date] | Only for /project_data gives you data where time is greater than the given date |
field=[field] | Only for specific field |
owner=[owner_id] | Only for specific owner ID |
|
|
Example output