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:
login
: the users login (this should be an email address)password
: the users password
If authentication failed an error response is returned with status code 403. If authentication is successful 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 :ref:`user details query <User details>`.
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:
eu-member
: country is a full EU member statecandidate-eu
: candidate member of the EUpotential-candidate-eu
: potentital candidate member of the EUefta
: member of the European Free Trade Associationregion
: generic region, not an individual country
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:
- Authenticate the user
- Start a new survey session
- Start identification phase and walk through all identification steps
- Start evaluation phase and walk through all evaluation steps
- Start action plan phase and walk through all action plan steps
All responses to API calls involving a survey session follow a standard structure. They include the following keys:
phase
: the current survey phase. This will be one ofidentification
,type
: an indicator of the response type. This will be one ofsurvey
,profile
,module
,risk
,update
orerror
.title
: the title for the current context. Depending on the context this will be the title of the survey, module or the risk.previous-step
: a URL pointing to the API location of the previous logical step. If the end start of the survey is reached this key will not be present.next-step
: a URL pointing to the API location of the next logical step. If the end of the survey is reached this key will not be present.
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", }
When looking at a module or risk you can ask for a context menu information to
be included in the response by adding a menu
parameter to the query
string. The parameter does not need to have a value.
The menu information is provided in a menu
key and formatted as a
nested dictionary reflecting the elements of a navigation tree. Each
element in the tree is an object with the following keys:
type
: node type (one ofrisk
ormodule
).number
: human presentable numbering for the node.title
: title of the risk or module.current
: boolean indicating if this is the current node. parent.active
: boolean indicating if this is a parent node of the current node.children
: list of child nodes (in the right order).url
: URL for the API interface to this node..status
: only present for risks and specifies the risk status. The value is one ofpostponed
,present
,not-present
or null if the user has not seen the risk yet.
Note
The content of the context menu depends on the currently active phase. Requesting the menu without specifying the phase will not return any menu data.
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:
survey
: path of the survey. This is a combination of the id of the sector id and survey id, separated by a slash.title
: title of the new session. This should default to the title of the survey itself.
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 :ref:`view action plan <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 :ref:`view action plan <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 :ref:`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. |