Admin system REST API
- Håkon Clausen
- Kristian Jacobsen (Unlicensed)
- Åsmund Johansen
This documents the possibility to interact with the admin system using REST calls (GET, POST, PUT, PATCH, DELETE) allowing automation of tasks like creating projects and users.
All examples are produced using the curl utility.
General
Authentification
The system uses BASIC AUTH authentification. Logging in simply need a admin system user and you can log in with the same username password combination that you uses for normal WEB access.
Data formats and URL's
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 (i.e. https://adm-us.drofus.com/) you are trying to access.
E.g. the link http://[admin-url]/projects gives the normal HTML project listing while and http://[admin-url]/projects.json gives the list with project and project users in JSON format(
Some resources (notable users) has 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 special endpoint for:
Resource | METHOD | Description |
|---|---|---|
/node/logins | GET | Get login statistics for projects for the last 5 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 time period, grouped by type of client used(Revit, dRofus etc.) |
/node/unique_users | GET | Gets 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 number of unique users for each project for the given period. |
/project_data?from_date=2018-01-01&to_date=2019-12-31 | GEt | Get statstics 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 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 contaning 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 the minimal data to provide when creating a new project
Parameter | Descriptione |
|---|---|
new_db | 1 to create a new database or 0 to add 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 | 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 | Descriptione |
|---|---|
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 user is superuser, this denies the 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 registred 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 database with name dbname |
/database/[dbname]/enableall | Enables all project users in database with name dbname |
/database/[dbname]/kickall | Logs out all users in database with name dbname |
/database/[dbname]/get_backup_now | Downloads a backup of the database |
Users
Resource |
|
|---|---|
/users/[username]/disable | Disables a users so he 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 of 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
Wherer data.json contains
Example 2: Update project user
Wherer data.json contains
DELETE Resources
You also use the DELETE operation to delete most object.
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 on email with a token:
To actually 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 | Gives you the latest project statistics for each project |
Filters
|
|
|---|---|
from_date=[date] | Only for /project_data, gives you only 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