Introduction¶
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.
Concepts¶
Country¶
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.
Sector¶
A sector is a national organisation for a single sector of industry.
API operations¶
Error responses¶
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",
}
Authentication¶
Verb | URI | Description |
---|---|---|
POST | /authenticate | Authenticate a user. |
In order to authenticate you must submit a JSON object with two keys:
- login: the users login name
- password: the users password
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.
Country management¶
List countries¶
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.
Country information¶
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:
- eu-member: country is a full EU member state
- candidate-eu: candidate member of the EU
- potential-candidate-eu: potentital candidate member of the EU
- efta: member of the European Free Trade Association
- region: 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 based on the id field.
Add a new country¶
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.
Update country information¶
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.
Country managers¶
List country managers¶
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,
},
],
}
Country manager information¶
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. |
Add new country manager¶
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.
Update country manager information¶
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.
Delete country manager¶
Verb | URI | Description |
---|---|---|
DELETE | /countries/<country id>/managers/<id> | Delete a country manager. |
Sector organisations¶
List sectors¶
Verb | URI | Description |
---|---|---|
GET | /countries/<country id>/sectors | List all sectors. |
Example response:
{
"sectors": [
{
"id": "security",
"title": "Security",
"login": "security",
"locked": false,
},
],
}
Sector information¶
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. |
Add new sector organisation¶
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.
Update sector information¶
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.
Delete sector organisation¶
Verb | URI | Description |
---|---|---|
DELETE | /countries/<country id>/sectors/<id> | Delete a sector. |
API reference¶
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. |