First steps and authentication
Introduction of PROAD API
The PROAD API is designed to provide read and write access to the basic entities such as projects, clients, prospects, time and material registrations and all todo types. In addition the api provides access to service entities such as countries, addresses. Key/value lists provide easy access to valid keys for several parameters.
The api access is restricted by user based rights, data rights, settings and licence restrictions.
Authentication is done by a api key which can be created for each user separately and must be send as a part of each request.
Authentication
To authenticate a request you need the PROAD API v5 module and the PROAD API configuration module. If the modules are installed you have a new right at
This right enables a menu item at the user menu.
Each user can request the API with all his rights considered. This means a user with no right to create a project can request the details of a project, update them but don't create a project or delete them. Data rights are also considered.
To create the api key navigate to the user menu form "PROAD API" and simply select "Enable API access". The api key will be displayed and don't forget to save it.
Each request needs this key as a "Header" property named "apikey" to authenticate you.
To test this you can use tools like "Postman" (https://www.getpostman.com/):
If everything is ok you should see this:
"infoid": "20001",
"infomessage": "api_key is valid"
}
If something went wrong a error will be shown, which means you should check your request.
"errorid": "40102",
"errormessage": "api_key is not valid"
}
Datatypes
| String | Strings are case-insensitive. Special chars must be url encoded. |
| Urno | Unique identifiers are called urnos and will be used to identify entities such as "project" or "company". These are simple integers values. To unset links between entities use urno=0. |
| Boolean | The only boolean values allowed are 1 for true and 0 for false. "true" and "false" are not allowed even when the swagger api documentation presents them as valid values. |
| Date/Datetime | Dates must be ISO 8601 formatted. For dates without a time "YYYY-MM-DD" (i.e. 2017-12-22) and for timestamps "YYYY-MM-DDTHH:MM:SS" (i.e. 2017-12-22T09:12:33). There is a way to filter a period of time by using the form "YYYY-MM-DD--YYYY-MM-DD". |
| Integer/Float | Can be written as 1234 for integers or 1.2345 for floating values. |
| Preset list | Some parameters use key values of preset lists. These keys can be selected by requesting the /preset_data endpoint. Example for all project type keys: https://[HOST]/api/v5/preset_data/projecttype Used lists are: projecttype, project_status, task_type, task_status, task_priority, bugtracker_bugtype, bugtracker_severity, service_code_category, address_type, product_use_in |
| User preset list | Some parameters use key values of user preset lists. These keys can be selected by requesting the /user_preset_data endpoint. Example for all business1 type keys: https://[HOST]/api/v5/user_preset_data/business1 Used lists are: business1, business2, bugtracker_subject, bugracker_planned_for, bugtracker_version |
Queries
Querytypes and examples
There are two different ways to request data from the API. Requesting a list of items or a single item. Requesting a single item is only possible for the root endpoints such as "projects", "clients" or "addresses". There is a way to select all addresses for a single client, but these endpoints are not capeable of selecting a single address, you have to request these from the root endpoint "addresses".
Examples of queries:
| https://[HOST]/api/clients | working, select a list of clients |
| https://[HOST]/api/clients/1234 | working, select a client with urno 1234 |
| https://[HOST]/api/clients/1234/addresses | working, select all addresses for client with urno 1234 |
| https://[HOST]/api/clients/1234/addresses/4 | not working, select the address with urno 4 from the client with urno 1234 |
| https://[HOST]/api/addresses/4 | working, instead select the address from the root endpoint "addresses" |
Get a single item
To select a specific item you have to request one of the root endpoints. The answer is a nested json object. All sub objects have the same information as if you select them from their root endpoint separately.
You need at least read rights for this to work.
REQUEST:
ANSWER:
"urno": 88,
"shortname": "DDE",
"name": "Donald Duck Empire",
"main_address": {
"urno": 88,
...
},
...
"active": true,
"external_id": null
}
Get a list of items
For all endpoints with no urno specified your request returns a list of items. These lists are limited in count by your systems "Selection limit" which can be modified at the "Server Manager" configuration page "Webserver", the default ist 2000.
The answer is also a nested json object, but the information delivered is far more limited then requesting a single item. If you need more information you need to request a single item.
Example queries:
| https://[HOST]/api/v5/clients | Select all clients |
| https://[HOST]/api/v5/clients?city=Hamburg | Select all clients from city Hamburg, note that filters are case-insensitive |
| https://[HOST]/api/v5/tasks?from_date=2017-12-01--2018-01-01 | Select all tasks which have a from date between first of december 2017 and first day of january in 2018. |
Filter parameters
Filter parameters can contain special characters which needed to be encoded. Please read the following documentation for further informations: https://www.w3schools.com/tags/ref_urlencode.asp.
Filter parameters are added as url parameters like this
For a summary of value types please read the "Datatypes" section.
Mutations
Create a new item
To create items you need a "POST" request. The information needed to create the item must be a JSON formatted body.
I.e. to create a project you can use the following JSON object:
"urno_company":6810,
"urno_manager":4,
"projectno":"12345",
"project_name":"test project",
"status":"100",
"orderno":"orderno",
"order_date":"2017-12-02",
"delivery_date":"2018-12-04",
"description":"we can describe this project"
}
If the item was created successfully the urno will be returned as the result or some error information otherwise.
On success the api returns a status code 200 and the urno:
"urno": 398
}
Update a item
To update a item you need a "PUT" request. The information needed to update the item must be JSON formatted body.
I.e. to update a project you can use the following JSON object:
"urno_company":6810,
"urno_manager":4,
"projectno":"12345",
"project_name":"test project",
"status":"100",
"orderno":"orderno",
"order_date":"2017-12-02",
"delivery_date":"2018-12-04",
"description":"we can describe this project"
}
If the item was updated successfully the urno will be returned as the result or some error information otherwise.
On success the api returns a status code 200 and the urno:
"urno": 1455
}
Delete a item
To delete a item you need a "DELETE" request with the urno of the item you want to delete.
On success the api returns:
"infoid": "20001",
"infomessage": "4004 successfully deleted"
}