This document describes the content management API for the Euphorie. This API allows interface with the CMS component of an Euphorie system and can be used to implement manage backend accounts.
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.
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 | /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 basic information on the user:
{
"token": "e1490672-4015-4572-a036-ba53c45e9509",
"login": "security",
"title": "UK security sector",
"url": "http://api.oira.com/countries/uk/sectors/security",
}
The token should be supplied in an X-Euphorie-Token HTTP header for all requests that require authentication.
Verb | URI | Description |
---|---|---|
GET | /countries | List all defined countries. |
Example response:
{
"countries": [
{
"id": "nl",
"title": "The Netherlands",
"country-type": "eu-member",
},
{
"id": "be",
"title": "Belgium",
"country-type": "eu-member",
},
}
This call will return information on all defined countries.
Verb | URI | Description |
---|---|---|
GET | /countries/<id> | Request country information. |
GET | /countries/<id>?details | Request country information including all sectors and country managers. |
Example normal response:
{
"type": "country",
"id": "nl",
"title": "The Netherlands",
"country-type": "eu-member",
}
Example detail response:
{
"type": "country",
"id": "nl",
"title": "The Netherlands",
"country-type": "eu-member",
"sectors": [
...
],
"managers": [
...
],
}
The returned fields are:
Field | Type | Required | |
---|---|---|---|
type | string | Yes | Always set to country. |
id | string | Yes | The country code. This must be the offical country code unless this is a generic region. |
title | string | No | The English title of the country. If not provided the name will be looked up based on the provided id. |
country-type | string | Yes | The country type. |
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 based on the id field.
Verb | URI | Description |
---|---|---|
POST | /countries | Add a new country. |
The request body must be a JSON block specifying the new profile:
{
"id": "nl",
"title": "The Netherlands",
"country-type": "eu-member",
}
This will return the country using the same format as the GET call.
Verb | URI | Description |
---|---|---|
PUT | /countries/<id> | Update country information. |
The request body must be a JSON block specifying the changed fields:
{
"title": "The Netherlands",
"country-type": "eu-member",
}
Updating the id field is not allowed.
Verb | URI | Description |
---|---|---|
GET | /countries/<country id>/managers | List all country managers |
Example response:
{
"managers": [
{
"id": "steunpunt-rie",
"title": "Steuntpunt RI&E",
"email": "steunpunt@example.com",
"login": "steunpunt",
"locked": false,
},
],
}
Verb | URI | Description |
---|---|---|
GET | /countries/<country id>/managers/<id> | Request manager information. |
Example response:
{
"type": "countrymanager",
"id": "steunpunt-rie",
"title": "Steuntpunt RI&E",
"email": "steunpunt@example.com",
"login": "steunpunt",
"locked": false,
}
The returned fields are:
Field | Type | Required | |
---|---|---|---|
type | string | Yes | Always set to countrymanager. |
id | string | Yes | Identifier for the manager. |
title | string | Yes | The full name of the country manager. |
string | Yes | Contact email address. | |
login | string | Yes | Login name for the account. |
locked | boolean | No | Indicates if the account is locked. |
Verb | URI | Description |
---|---|---|
POST | /countries/<country id>/managers | Add a new country manager. |
The request body must be a JSON block with the necessary information:
{
"title": "Steuntpunt RI&E",
"email": "steunpunt@example.com",
"login": "steunpunt",
"locked": false,
}
Please note that the id field can not be set manually: it will be generated automatically.
This will return the country manager information in the same format as returned by the GET call.
Verb | URI | Description |
---|---|---|
PUT | /countries/<country id>/managers/<id> | Update country manager information. |
The request body must be a JSON block with the data that should be updated:
{
"locked": true,
}
Please note that the id and login fields can not be modified.
This will return the country manager information in the same format as returned by the GET call.
Verb | URI | Description |
---|---|---|
DELETE | /countries/<country id>/managers/<id> | Delete a country manager. |
Verb | URI | Description |
---|---|---|
GET | /countries/<country id>/sectors | List all sectors. |
Example response:
{
"sectors": [
{
"id": "security",
"title": "Security",
"login": "security",
"locked": false,
},
],
}
Verb | URI | Description |
---|---|---|
GET | /countries/<country id>/sectors/<id> | Request sector information. |
Example response:
{
"type": "sector",
"id": "security",
"title": "Security",
"login": "security",
"locked": false,
"contact": {
"name": "John Smith",
"email": "smith@example.com",
},
}
The returned fields are:
Field | Type | Required | |
---|---|---|---|
type | string | Yes | Always set to sector. |
id | string | Yes | Identifier for the sector. |
title | string | Yes | The full name of the sector |
login | string | Yes | Login name for the account. |
locked | boolean | No | Indicates if the account is locked. |
contact | object | Yes | Object specifying a contact for the sector organisation. This must have the following keys: name and email. |
Verb | URI | Description |
---|---|---|
POST | /countries/<country id>/sectors | Add a new sector. |
The request body must be a JSON block with the necessary information:
{
"title": "Security",
"login": "security",
"locked": false,
"contact": {
"name": "John Smith",
"email": "smith@example.com",
},
}
Please note that the id field can not be set manually: it will be generated automatically.
This will return the sector information in the same format as returned by the GET call.
Verb | URI | Description |
---|---|---|
PUT | /countries/<country id>/sectors/<id> | Update sector information. |
The request body must be a JSON block with the data that should be updated:
{
"locked": true,
}
Please note that the id and login fields can not be modified.
This will return the country manager information in the same format as returned by the GET call.
Verb | URI | Description |
---|---|---|
DELETE | /countries/<country id>/sectors/<id> | Delete a sector. |
Verb | URI | Description |
---|---|---|
POST | /authenticate | Authenticate a user. |
GET | /countries | List all defined countries. |
GET | /countries/<id> | Request country information. |
GET | /countries/<id>?details | Request country information including all sectors and country managers. |
POST | /countries | Add a new country. |
PUT | /countries/<id> | Update country information. |
GET | /countries/<country id>/managers | List all country managers |
GET | /countries/<country id>/managers/<id> | Request manager information. |
POST | /countries/<country id>/managers | Add a new country manager. |
PUT | /countries/<country id>/managers/<id> | Update country manager information. |
DELETE | /countries/<country id>/managers/<id> | Delete a country manager. |
GET | /countries/<country id>/sectors | List all sectors. |
GET | /countries/<country id>/sectors/<id> | Request sector information. |
POST | /countries/<country id>/sectors | Add a new sector. |
PUT | /countries/<country id>/sectors/<id> | Update sector information. |
DELETE | /countries/<country id>/sectors/<id> | Delete a sector. |