This document describes the client API for the Euphorie. This API allows interface with the client component of an Euphorie system and can be used to implement a custom frontend. It exposes client users, surveys, surveys sessions and all interactions with them. It does not allow for management of sectors or surveys: this must be done through the standard Euphorie CMS system.
A country is the top level grouping item for survey content. There are different country types to indicate the EU membership status. A country contains zero or more sectors.
A sector is a national organisation for a single sector of industry. A sector can have zero or more surveys.
A survey is a hierarchical questionnaire used identify risks in an environment and build a plan to tackle them.
A session is an instance of a survey as created by a user and contains all information provided by the user.
An error can occur for several reasons: bad data being passed to an API call, Euphorie encountering an internal error, a disk running out of space, etc. If this happens an error-response will be returned. These can be recognized by the type key being set to error.
{
"type": "error",
"message": "Required data missing",
}
Verb | URI | Description |
---|---|---|
POST | /users | Create a new user. |
Using this call you can create a new user. The user information must be supplied in a JSON dictionary:
{
"login": "jane@example.com",
"password": "john",
}
The login key is required. Specifying the password is optional: if a password is given the user can login with that password on the Euphorie client directly. If no password is given access is only possible with the authentication token returned by this call.
The response is a JSON dictionary with details for the newly created account:
{
"token": "e1490672-4015-4572-a036-ba53c45e9509",
"id": 17,
"login": "jane@example.com",
"email": "jane@example.com",
}
If the login is not a valid email address or another account with the same email address already exists an error is returned.
Verb | URI | Description |
---|---|---|
POST | /users/authenticate | Authenticate a user. |
In order to authenticate you must submit a JSON object with two keys:
If authentication failed an error response is returned with status code 403. If authentication is succesful a JSON response is returned with an authentication token and a list of existing sessions:
{
"token": "e1490672-4015-4572-a036-ba53c45e9509",
"id": 17,
"login": "jane@example.com",
"email": "jane@example.com",
"sessions": [
{
"id": 1926,
"title": "Hoveniers en Groenvoorzieners",
"created": "2010-09-27T11:35:00Z",
"modified": "2012-04-23T10:29:13Z",
},
{
"id": 23945,
"title": "Vlakglas",
"created": "2010-09-27T11:35:00Z",
"modified": "2012-04-23T10:29:13Z",
},
],
}
The token should be supplied in an X-Euphorie-Token HTTP header for all requests that require authentication.
Verb | URI | Description |
---|---|---|
GET | /users/<userid> | Return user information. |
This will return information about the user, including all known sessions. A user can only request information for his own account: any attempt to request information on another user will result in a HTTP 403 error response.
{
"id": 17,
"login": "jane@example.com",
"email": "jane@example.com",
"sessions": [
{
"id": 1926,
"title": "Hoveniers en Groenvoorzieners",
"created": "2010-09-27T11:35:00Z",
"modified": "2012-04-23T10:29:13Z",
},
{
"id": 23945,
"title": "Vlakglas",
"modified": "2011-12-06T15:15:24Z",
},
],
This token should be supplied in an X-Euphorie-Token HTTP header for all requests that require authentication.
Verb | URI | Description |
---|---|---|
PUT | /users/<userid> | Update user information. |
This call allows updating the user information. The only key that can be updated is login. Currently the login name and email address are defined to be the same, so updating the login will also update the users email address.
{
"login": "jane@example.com",
"password": "bruce",
}
The response is identical to the user details query.
Verb | URI | Description |
---|---|---|
GET | /surveys | List all defined countries |
Example response:
{
"countries": [
{
"id": "nl",
"title": "The Netherlands",
"type": "eu-member",
},
{
"id": "be",
"title": "Belgium",
"type": "eu-member",
},
}
The possible country types are:
Note that even though a country has a title frontends are encouraged to use use locale-specific name for the country. This can be based on the id, which is guaranteed to be a valid country code.
Verb | URI | Description |
---|---|---|
GET | /surveys/<country> | List all sectors in a country. |
GET | /surveys/<country>?details | List all sectors in a country including its surveys. |
GET | /surveys/<country>?details&language=<lang> | List all sectors in a country including all surveys in the given language. |
Example response:
{
"id": "nl",
"title": "The Netherlands",
"type": "eu-member",
"sectors": [
{
"id": "bovag",
"title": "BOVAG",
},
{
"id": "bovag",
"title": "BOVAG",
},
}
Example detail response:
{
"id": "nl",
"title": "The Netherlands",
"type": "eu-member",
"sectors": [
{
"id": "stigas",
"title": "STIGAS",
"surveys": [
{
"id": "akkerbouw-en-vollegrondsgroenteteelt",
"title": "Akkerbouw en vollegrondsgroenteteelt",
"language": "nl",
},
{
"id": "bos-en-natuur",
"title": "Bos en natuur",
"language": "nl",
}
,
],
},
{
"id": "dierenartsen",
"title": "Dierenartsen",
"surveys": [
{
"id": "dierenartsen",
"title": "Dierenartsen",
"language": "nl",
},
],
},
}
Verb | URI | Description |
---|---|---|
GET | /surveys/<country>/<sectorid> | List details of the given sector. |
GET | /surveys/<country>/<sectorid>?language=<lang> | List details of the given sector, only including surveys in the given language. |
Example response:
{
"id": "stigas",
"title": "STIGAS",
"surveys": [
{
"id": "nl/akkerbouw-en-vollegrondsgroenteteelt",
"title": "Akkerbouw en vollegrondsgroenteteelt",
"language": "nl",
},
{
"id": "nl/bos-en-natuur",
"title": "Bos en natuur",
"language": "nl",
},
],
}
The general structure for interacting with a survey is as follows:
All responses to API calls involving a survey session follow a standard structure. They include the following keys:
If a survey was updated since the last interaction of the user with the survey and the structure of the survey has changed a survey-update response is generated. The response type can be identified by type set to update.
{
"type": "update",
"confirm-profile": true,
"next-step": "http://api.instrumenten.rie.nl/users/13/sessions/193714/update",
}
Verb | URI | Description |
---|---|---|
POST | /users/<userid>/sessions | Start a new survey session. |
To start a new survey session a POST request must be send. This must include a JSON body with the following keys:
This requires that the user already authenticated and a suitable authentication token is set in the X-Euphorie-Token header.
Here is an example request:
{
"survey": "nl/stigas/bos-en-natuur",
"title": "Beheer stadspark oost",
}
The response will be a JSON block:
{
"id": "193714",
"survey": "nl/stigas/bos-en-natuur",
"type": "session",
"title": "Beheer stadspark oost",
"introduction": "Introduction text from the survey.",
"next-step: "http://api.instrumenten.rie.nl/users/13/sessions/193714/profile",
}
If the survey has a configurable profile next-step will either to the profile update API. For surveys without profile questions next-step will point directly to the start of the identification phase.
Verb | URI | Description |
---|---|---|
GET | /users/<userid>/sessions/<survey id> | Get information on survey. |
Note
This is also the API interface to use when resuming an existing survey session.
This function returns almost exactly the same response as the survey session creation method. The only difference is the addition of a modified entry.
{
"id": "193714",
"survey": "nl/stigas/bos-en-natuur",
"type": "session",
"created": "2011-12-06T15:15:24Z",
"modified": "2012-04-23T10:29:13Z",
"title": "The title of the survey",
"introduction": "Introduction text from the survey.",
"next-step: "http://api.instrumenten.rie.nl/users/13/sessions/193714/profile",
}
Verb | URI | Description |
---|---|---|
DELETE | /users/<userid>/sessions/<session id> | Delete a survey session. |
This will delete an existing survey session.
Verb | URI | Description |
---|---|---|
GET | /users/<userid>/sessions/<session id>/profile | Get survey profile. |
The response will be a JSON block:
{
"id": 15,
"type": "profile",
"title": "The title of the survey",
"profile": [
{
"id": "1",
"type": "optional",
"question": "Do you have a storeroom?",
"value": false,
},
{
"id": "3",
"type": "repetable",
"question": "Enter your shop locations",
"value": [
"New York",
"Paris",
],
},
],
}
Note
As you can see in the example the response does not have previous-step or next-step information.
The id is set to the survey id. Please note that not all surveys have a profile, so the profile list might be empty.
Verb | URI | Description |
---|---|---|
PUT | /users/<userid>/sessions/<session id>/profile | Update survey profile. |
The request body must be a JSON block specifying the new profile:
{
"1": false,
"3": [
"New York",
"Paris",
],
}
It is mandatory that all profile questions are included in the request data. If data for a question is missing or invalid an error will be returned.
The response to a profile update returns the same information as the profile information view. The id of the survey may change as a result of a profile update.
{
"id": 15,
"type": "profile",
"title": "The title of the survey",
}
Verb | URI | Description |
---|---|---|
GET | /users/<userid>/sessions/<session id>/update | Get update information. |
PUT | /users/<userid>/sessions/<session id>/update | Confirm survey update. |
If a survey was updated since the last user interaction and the survey structure was changed (for example a new risk has been added) the user must acknowledge the change and request that his survey session is updated accordingly.
These calls return the same information as the `profile information<View profile information>`_ and update profile calls. The only difference is that the type got a GET query will be set to update.
Verb | URI | Description |
---|---|---|
GET | /users/<userid>/sessions/<session id>/identification | Request idenfication info. |
This call will return information that is needed to start the identification phase in a survey. A frontend may not need to display any of this information but only use it to find locate the first unanswered question in the survey session, which is given in the next-step key.
{
"type": "session",
"phase": "identification",
"title": "The title of the survey",
"next-step": "http://api.instrumenten.rie.nl/users/13/sessions/1931714/1",
"menu": [ ... ],
}
Verb | URI | Description |
---|---|---|
GET | /users/<userid>/sessions/<session id>/evaluation | Request evaluation info. |
This call will return information that is needed to start the evaluation phase in a survey. A frontend may not need to display any of this information but only use it to find locate the first unanswered evaluation question in the survey session, which is given in the next-step key.
{
"type": "session",
"phase": "evaluation",
"title": "The title of the survey",
"next-step": "http://api.instrumenten.rie.nl/users/13/sessions/1931714/2/5/13",
"menu": [ ... ],
}
Verb | URI | Description |
---|---|---|
GET | /users/<userid>/sessions/<session id>/actionplan | Request evaluation info. |
This call will return information that is needed to start the action plan phase in a survey. A frontend may not need to display any of this information but only use it to find locate the first unanswered action plan question in the survey session, which is given in the next-step key.
{
"type": "session",
"phase": "actionplan",
"title": "The title of the survey",
"next-step": "http://api.instrumenten.rie.nl/users/13/sessions/1931714/2/5/13",
"menu": [ ... ],
}
Verb | URI | Description |
---|---|---|
GET | /users/<userid>/sessions/<session id>/<path> | Request module information |
GET | /users/<userid>/sessions/<session id>/<path>/<phase> | Request module information for the given phase. |
Note
The URL does not indicate if the data at that location is a module or a risk. That means a client must check the returned type information to determine the resource type and act accordingly.
previous-step and next-step can only be returned if the phase is provided. The phase must be one of identification, evaluation or actionplan.
Beyond the standard fields a module will return these extra fields:
Field | Type | Required | |
---|---|---|---|
image | object | No | An image related to the module. This has three keys: original, thumbnail and caption. |
solution-direction | string (HTML) | No | Explanation of how to handle risks in this module. |
optional | boolean | Yes | Flag indicating if this module is optional. |
question | string | No | For optional modules this is the question to ask users to determine if children of this module should be included or skipped. |
skip-children | boolean | No | The users answer to the question. If the question has not been answered yet this is set to null. |
Verb | URI | Description |
---|---|---|
PUT | /users/<userid>/sessions/<session id>/<path>/identification | Update module status |
This call is only useful for optional modules. For normal (ie mandatory) modules it is an error to use this call.
The request must be a JSON block with an answer for the skip-children flag:
{
"skip-children": false,
}
Verb | URI | Description |
---|---|---|
GET | /users/<userid>/sessions/<session id>/<path> | Request risk information |
GET | /users/<userid>/sessions/<session id>/<path>/<phase> | Request risk information for the given phase. |
Note
The URL does not indicate if the data at that location is a module or a risk. That means a client must check the returned type information to determine the resource type and act accordingly.
previous-step and next-step can only be returned if the phase is provided. The phase must be one of identification, evaluation or actionplan.
Beyond the standard fields a risk will return these extra fields:
Field | Type | Required | |
---|---|---|---|
module-title | string | Yes | The title of the parent module. |
problem-description | string | Yes | The inverse of the risk title. This should be used instead of the title if risk is known to be present. |
evaluation-method | string | Yes | The evaluation method to use. Will be either direct or calcualated. |
images | list of objects | No | An list of image related to the risk. Each entry is an object with three keys: original, thumbnail and caption. |
standard-solutions | list of objects | No | A list of standard solutions for this risk. Each entry is with four keys: description, action-plan, prevention-plan and requirements. |
legal-reference | string (HTML) | No | A reference to related legal and policy references. |
show-not-applicable | boolean | Yes | Indicates of a not applicable option should be offered in the identification phase. |
present | string | Yes | Indicates if the risk is present. One of yes, no, n/a (only if show-not-applicable is set) or null of not yet known. |
priority | string | Yes | The priority of the risk. One low, medium, high or null if not known yet. |
comment | string | No | A comment added by the user. |
For risks with an evalution option of calculated these extra fields are included:
Field | Type | Required | |
---|---|---|---|
frequency-options | list of objects | Yes | A list of allowed frequency answers. Each entry is an object with two string keys: value and title. |
frequency | integer | Yes | Users answer to the frequency question. |
effect-options | list of objects | Yes | A list of allowed effect answers. Each entry is an object with two string keys: value and title. |
effect | integer | Yes | Users answer to the effect question. |
probability-options | list of objects | Yes | A list of allowed probability answers. Each entry is an object with two string keys: value and title. |
probability | integer | Yes | Users answer to the probability question. |
Verb | URI | Description |
---|---|---|
PUT | /users/<userid>/sessions/<session id>/<path>/identification | Update risk status |
The request must be a JSON block with a (new) answer for the present flag. The comment can also be updated by including the comment field.
{
"present": "no",
"comment": "Verify with John at the shipping department!",
}
Verb | URI | Description |
---|---|---|
PUT | /users/<userid>/sessions/<session id>/<path>/evaluation | Update risk status |
The possbile values depend on the evaluation method used for the risk. For risks that use a direct evaluation the priority field can be set directly. For risks using a calculated evaluation method the frequency, effect and probability information must be provided.
The comment can also be updated by including the comment field.
{
"frequency": 10,
"effect": 3,
"probability": 7,
}
Verb | URI | Description |
---|---|---|
PUT | /users/<userid>/sessions/<session id>/<path>/actionplan | Update risk status |
This method updates the action plan-specific information for a risk. For top-5 and policy risks only the commend field may be updated. For other risks the priority can be set directly as well (but it may be reset of the user re-evaluates the risk).
The possible values for priority are low, medium and high.
{
"comment": "We need to take another look at this",
"priority": "medium",
}
Action plans can be added, updated or deleted through the actionplans container (see below).
Verb | URI | Description |
---|---|---|
GET | /users/<userid>/sessions/<session id>/<path>/actionplans | List action plans |
During the action plan phase a user is asked to indicate how he wants to tackle a risk by defining specific actions to be taken. This API call will return a list of all action plans provided by the user.
The response is returned in the form of a JSON object with a action-plans key containing a list of plans.
{
"action-plans": [
{
"id": 15,
"plan": "Clean the workplace",
"prevention": "Educate workers to clean daily.",
"requirements": "Soap, vacuumcleaner",
"responsible": "John Doe",
"budget": 1500,
"planning-start": "2012-04-15",
"planning-end": null,
"reference": "2012a16.5",
},
],
}
See the view action plan call for details on the returned information.
Verb | URI | Description |
---|---|---|
GET | /users/<userid>/sessions/<session id>/<path>/actionplans/<id> | View action plan details. |
The response is returned in the form of a JSON object containing all known information about an action plan.
{
"type": "actionplan",
"id": 15,
"plan": "Clean the workplace",
"prevention": "Educate workers to clean daily.",
"requirements": "Soap, vacuumcleaner",
"responsible": "John Doe",
"budget": 1500,
"planning-start": "2012-04-15",
"planning-end": null,
"reference": "2012a16.5",
}
The reference key is not part of the standard Euphorie user interface, but can be used by consumers of this API to link a measure to an external system.
Verb | URI | Description |
---|---|---|
POST | /users/<userid>/sessions/<session id>/<path>/actionplans | Add new action plan. |
The request must be a JSON object with data for the action plan to be added. The only required field is plan; all either items are optional.
Field | Type | Required | |
---|---|---|---|
plan | string string | Yes | Description of actions needed to remove the current risk. |
prevention | string | No | Description of what should be done to remove this risk. |
requirements | string | No | A description of the requirements for this plan. |
responsible | string | No | The name of the person or group who is available for this task. |
budget | integer | No | The budget that is available for this task. |
planning-start | string (ISO date) | No | Start date for the plan. |
planning-end | string (ISO date) | No | Completion date for the plan. |
reference | string | No | Reference to external system. |
The reference key is not part of the standard Euphorie user interface, but can be used by consumers of this API to link a measure to an external system.
The response is a JSON object with complete information on the newly created action plan. See the view action plan call for details.
Verb | URI | Description |
---|---|---|
PUT | /users/<userid>/sessions/<session id>/<path>/actionplans/<id> | Update an action plan. |
The request must be a JSON object with all items that must be updated. Items not included in the request will not be changed.
Verb | URI | Description |
---|---|---|
DELETE | /users/<userid>/sessions/<session id>/<path>/actionplans/<id> | Remove an action plan. |
This call will remove an action plan for a risk.
Verb | URI | Description |
---|---|---|
GET | /users/<userid>/sessions/<session id>/company | Request company information |
This interface will return information about the company to which this survey session applies. The response is returned in the form of a JSON object containing all known information about the company. The possible fields are:
Field | Type | Required | |
---|---|---|---|
country | string | No | ISO country code. . |
employees | string | No | Indicator of company size in terms of number of employees. One of 1-9, 10-49, 50-249 or 250+. |
conductor | string | No | Role of person who conducted the survey. Must be one of staff, third-party or both. |
referer | string | No | How the user learned about the tool. Must be one of employers-organisation, trade-union, national-public-institution eu-institution health-safety-experts or other. |
Verb | URI | Description |
---|---|---|
PUT | /users/<userid>/sessions/<session id>/company | Update company details. |
This interface will update the company information for a survey session. See the View company details section for the supported fields.
Verb | URI | Description |
---|---|---|
GET | /users/<userid>/sessions/<survey id>/report-identification | Download identifcation report. |
This API call will return the identification report. This is returned as a downloadable RTF file.
Verb | URI | Description |
---|---|---|
GET | /users/<userid>/sessions/<survey id>/report-actionplan | Download action plan report. |
This API call will return the action plan report. This is returned as a downloadable RTF file.
Verb | URI | Description |
---|---|---|
GET | /users/<userid>/sessions/<survey id>/report-timeline | Download action plan timeline. |
This API call will return the action plan timeline. This is returned as a downloadable OpenXML (xlsx) file.
Verb | URI | Description |
---|---|---|
POST | /users | Create a new user. |
POST | /users/authenticate | Authenticate a user. |
GET | /users/<userid> | Return user information. |
PUT | /users/<userid> | Update user information. |
GET | /surveys | List all defined countries |
GET | /surveys/<country> | List all sectors in a country. |
GET | /surveys/<country>?details | List all sectors in a country including its surveys. |
GET | /surveys/<country>?details&language=<lang> | List all sectors in a country including all surveys in the given language. |
GET | /surveys/<country>/<sectorid> | List details of the given sector. |
GET | /surveys/<country>/<sectorid>?language=<lang> | List details of the given sector, only including surveys in the given language. |
POST | /users/<userid>/sessions | Start a new survey session. |
GET | /users/<userid>/sessions/<survey id> | Get information on survey. |
DELETE | /users/<userid>/sessions/<session id> | Delete a survey session. |
GET | /users/<userid>/sessions/<session id>/profile | Get survey profile. |
PUT | /users/<userid>/sessions/<session id>/profile | Update survey profile. |
GET | /users/<userid>/sessions/<session id>/update | Get update information. |
PUT | /users/<userid>/sessions/<session id>/update | Confirm survey update. |
GET | /users/<userid>/sessions/<session id>/identification | Request idenfication info. |
GET | /users/<userid>/sessions/<session id>/evaluation | Request evaluation info. |
GET | /users/<userid>/sessions/<session id>/actionplan | Request evaluation info. |
GET | /users/<userid>/sessions/<session id>/<path> | Request module information |
GET | /users/<userid>/sessions/<session id>/<path>/<phase> | Request module information for the given phase. |
PUT | /users/<userid>/sessions/<session id>/<path>/identification | Update module status |
GET | /users/<userid>/sessions/<session id>/<path> | Request risk information |
GET | /users/<userid>/sessions/<session id>/<path>/<phase> | Request risk information for the given phase. |
PUT | /users/<userid>/sessions/<session id>/<path>/identification | Update risk status |
PUT | /users/<userid>/sessions/<session id>/<path>/evaluation | Update risk status |
PUT | /users/<userid>/sessions/<session id>/<path>/actionplan | Update risk status |
GET | /users/<userid>/sessions/<session id>/<path>/actionplans | List action plans |
GET | /users/<userid>/sessions/<session id>/<path>/actionplans/<id> | View action plan details. |
POST | /users/<userid>/sessions/<session id>/<path>/actionplans | Add new action plan. |
PUT | /users/<userid>/sessions/<session id>/<path>/actionplans/<id> | Update an action plan. |
DELETE | /users/<userid>/sessions/<session id>/<path>/actionplans/<id> | Remove an action plan. |
GET | /users/<userid>/sessions/<session id>/company | Request company information |
PUT | /users/<userid>/sessions/<session id>/company | Update company details. |
GET | /users/<userid>/sessions/<survey id>/report-identification | Download identifcation report. |
GET | /users/<userid>/sessions/<survey id>/report-actionplan | Download action plan report. |
GET | /users/<userid>/sessions/<survey id>/report-timeline | Download action plan timeline. |