Introduction
OpenVeo offers a Web Service which must be started as a different process and needs some extra configuration.
Configure the Web Service
Open ~openveo/core/serverConf.json
{
"ws" : {
"port" : PORT // Replace PORT by the HTTP server port to use (e.g. 3002)
}
}
Configure the Web Service logger
Open ~openveo/core/loggerConf.json
{
"ws" : {
"fileName" : "/var/log/openveo/openveo-ws.log", // Path to web service log file
"level" : "info", // Log level
"maxFileSize" : 104857600, // Maximum log file size (in Bytes)
"maxFiles" : 2 // Maximum number of files archived
}
}
Launch the Web Service
If you want to interact with OpenVeo through the Web Service, you need to start it. To start the OpenVeo Web Service, just use the -ws option:
node server.js -ws
Authenticate to the Web Service
The Web Service uses OAuth2 for authentication.
Get a client id and client secret
You can create a new application with a client id and a client secret through the back end (http://localhost:PORT/be/applications-list
).
Get an access token
To make Web Service requests you will need an Access token. To get an Access token, you must make an HTTP POST request on /token.
Expected headers :
- 'Authorization: Basic CREDENTIALS' (Replace CREDENTIALS by "CLIENT_ID:CLIENT_SECRET" encoded in base 64)
Expected POST parameters :
- 'grant_type' => 'client_credentials'
You will receive an Access token to authenticate each Web Service requests.
PHP example
$curlCookieJar = tempnam(sys_get_temp_dir(), "cookies_");
// Initialize a curl session
$curlHandle = curl_init();
// Default curl options for all future requests
curl_setopt($curlHandle, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_COOKIESESSION, false);
curl_setopt($curlHandle, CURLOPT_COOKIEJAR, $curlCookieJar);
curl_setopt($curlHandle, CURLOPT_COOKIEFILE, $curlCookieJar);
curl_setopt($curlHandle, CURLOPT_HEADER, false);
curl_setopt($curlHandle, CURLOPT_CONNECTTIMEOUT, 1);
curl_setopt($curlHandle, CURLOPT_TIMEOUT, 30);
// Retrieve an oauth token
// Use HTTP POST method
curl_setopt($curlHandle, CURLOPT_CUSTOMREQUEST, 'POST');
// Replace {OPENVEO_URL} by the openveo server url
curl_setopt($curlHandle, CURLOPT_URL, '{OPENVEO_URL}/token');
// Replace {CLIENT_ID} and {CLIENT_SECRET} by your credentials
curl_setopt($curlHandle, CURLOPT_HTTPHEADER, array(
'Authorization: Basic ' . base64_encode('{CLIENT_ID}:{CLIENT_SECRET}'),
'Content-Type: application/json'
));
// Set oauth grant type to client_credentials
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, json_encode(array(
'grant_type' => 'client_credentials'
)
));
$resultWithToken = json_decode(curl_exec($curlHandle));
Authenticate a request
All requests to the Web Service must be authenticated using the HTTP header:
- 'Authorization: Bearer TOKEN' (Replace TOKEN by your access token)
PHP example
// Get the list of videos
curl_setopt($curlHandle, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlHandle, CURLOPT_URL, '{OPENVEO_URL}/taxonomies');
curl_setopt($curlHandle, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $resultWithToken->access_token
));
// Got the list of videos
$videos = json_decode(curl_exec($curlHandle));
Endpoints
Taxonomies
Get taxonomies.
GET WEB_SERVICE_URL/taxonomies
Name | Type | Required | Default | Details |
---|---|---|---|---|
query | String | No | - | To search on taxonomy names |
sortBy | String | No | name | The field to use to sort taxonomies. Only name is available right now |
sortOrder | String | No | desc | The sort order (either asc or desc) |
page | Number | No | 0 | The expected page |
limit | Number | No | 10 | The limit the number of taxonomies per page |
include | Array | No | - | The list of fields to include from returned taxonomies |
exclude | Array | No | - | The list of fields to exclude from returned taxonomies. Ignored if include is also specified |
HTTP Status Code | Details |
---|---|
200 | Got the list of taxonomies |
500 | An error occured on the server side |
400 | Wrong list of parameters |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities": [
{
"id": "1443533344313",
"name": "Taxonomy 1",
"tree": [
{
"id": "1445433239636",
"items": [],
"title": "Term 1"
}
]
},
{
"id": "1333443134453",
"name": "Taxonomy 2",
"tree": [
{
"id": "3239636144543",
"items": [],
"title": "Term 1"
}
]
}
],
"pagination": {
"limit": 1,
"page": 1,
"pages": 2,
"size": 2
}
}
Get a taxonomy.
GET WEB_SERVICE_URL/taxonomies/{taxonomy_id}
With {taxonomy_id} the id of the taxonomy to retrieve.
Name | Type | Required | Default | Details |
---|---|---|---|---|
include | Array | No | - | The list of fields to include from returned taxonomy |
exclude | Array | No | - | The list of fields to exclude from returned taxonomy. Ignored if include is also specified |
HTTP Status Code | Details |
---|---|
200 | Got the taxonomy |
500 | An error occured on the server side |
400 | Missing the taxonomy id |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
404 | Taxonomy not found |
{
"entity": {
"name": "My taxonomy",
"id": "{taxonomy_id}",
"tree": []
}
}
Get the list of terms of a taxonomy.
GET WEB_SERVICE_URL/taxonomies/{taxonomy_id}/terms
HTTP Status Code | Details |
---|---|
200 | Got the taxonomy terms |
500 | An error occured on the server side |
400 | Missing the taxonomy id |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"terms": [
{
"id": "1445433239636",
"title": "Term 1",
"items": [
{
"id": "1445433239637",
"items": [],
"title": "Sub term 1"
}
]
},
{
"title": "Term 2",
"id": "1333443134453",
"items": []
}
]
}
Add taxonomies.
PUT WEB_SERVICE_URL/taxonomies
Expects an Array of objects containing:
Name | Type | Required | Default | Details |
---|---|---|---|---|
name | String | Yes | - | The taxonomy name |
tree | Array | No | - | The list of terms for the taxonomy |
HTTP Status Code | Details |
---|---|
200 | The taxonomies have been added |
500 | An error occured on the server side |
400 | Missing body |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities": [
{
"name": "My taxonomy",
"id": "41U3sYipg",
"tree": []
},
...
],
"total": 42
}
Update a taxonomy.
POST WEB_SERVICE_URL/taxonomies/{taxonomy_id}
With {taxonomy_id} the id of the taxonomy to update.
Name | Type | Required | Default | Details |
---|---|---|---|---|
name | String | No | - | The taxonomy name |
tree | Array | No | - | The list of terms for this taxonomy |
HTTP Status Code | Details |
---|---|
200 | The taxonomy has been updated |
500 | An error occured on the server side |
400 | Missing the taxonomy id or body |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 1
}
Delete taxonomies.
DELETE WEB_SERVICE_URL/taxonomies/{taxonomy_id}
With {taxonomy_id} a comma separated list of taxonomy ids to delete.
HTTP Status Code | Details |
---|---|
200 | The taxonomies have been deleted |
500 | An error occured on the server side |
400 | Missing the taxonomy ids |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 42
}
Groups
Get groups.
GET WEB_SERVICE_URL/groups
Name | Type | Required | Default | Details |
---|---|---|---|---|
query | String | No | - | To search on both group names and descriptions |
sortBy | String | No | name | The field to use to sort groups (either name or description) |
sortOrder | String | No | desc | The sort order (either asc or desc) |
page | Number | No | 0 | The expected page |
limit | Number | No | 10 | The limit the number of groups per page |
include | Array | No | - | The list of fields to include from returned groups |
exclude | Array | No | - | The list of fields to exclude from returned groups. Ignored if include is also specified |
HTTP Status Code | Details |
---|---|
200 | Got the list of groups |
500 | An error occured on the server side |
400 | Wrong list of parameters |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities": [
{
"id": "Nk0fPIulZ",
"name": "Group name",
"description": "Group description"
},
{
"id": "VJfQDIul-",
"name": "Group name",
"description": "Group description"
}
],
"pagination": {
"limit": 1,
"page": 1,
"pages": 2,
"size": 2
}
}
Get a group.
GET WEB_SERVICE_URL/groups/{group_id}
With {group_id} the id of the group to retrieve.
Name | Type | Required | Default | Details |
---|---|---|---|---|
include | Array | No | - | The list of fields to include from returned group |
exclude | Array | No | - | The list of fields to exclude from returned group. Ignored if include is also specified |
HTTP Status Code | Details |
---|---|
200 | Got the group |
500 | An error occured on the server side |
400 | Missing the id of the group |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
404 | Group not found |
{
"entity": {
"id": "{group_id}",
"name": "Group name",
"description": "Group description"
}
}
Add groups.
PUT WEB_SERVICE_URL/groups
Expects an Array of objects containing:
Name | Type | Required | Default | Details |
---|---|---|---|---|
name | String | Yes | - | The group name |
description | String | Yes | - | The group description |
HTTP Status Code | Details |
---|---|
200 | The groups have been added |
500 | An error occured on the server side |
400 | Missing body |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities": [
{
"id": "41U3sYipg",
"name": "Group name",
"description": "Group description"
},
...
],
"total": 42
}
Update a group.
POST WEB_SERVICE_URL/groups/{group_id}
With {group_id} the id of the group to update.
Name | Type | Required | Default | Details |
---|---|---|---|---|
name | String | No | - | The group name |
description | String | No | - | The group description |
HTTP Status Code | Details |
---|---|
200 | The group has been updated |
500 | An error occured on the server side |
400 | Missing the group id or the body |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 1
}
Delete groups.
DELETE WEB_SERVICE_URL/groups/{group_id}
With {group_id} a comma separated list of group ids to delete.
HTTP Status Code | Details |
---|---|
200 | The groups have been deleted |
500 | An error occured on the server side |
400 | Missing the group ids |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 42
}
Roles
Get roles.
GET WEB_SERVICE_URL/roles
Name | Type | Required | Default | Details |
---|---|---|---|---|
query | String | No | - | To search on role names |
sortBy | String | No | name | The field to use to sort results, only name is available right now |
sortOrder | String | No | desc | The sort order (either asc or desc) |
page | Number | No | 0 | The expected page |
limit | Number | No | 10 | The limit the number of roles per page |
include | Array | No | - | The list of fields to include from returned roles |
exclude | Array | No | - | The list of fields to exclude from returned roles. Ignored if include is also specified |
HTTP Status Code | Details |
---|---|
200 | Got the list of roles |
500 | An error occured on the server side |
400 | Wrong list of parameters |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities": [
{
"id": "4J5KIL_lb",
"name": "Role name",
"permissions" : [...]
}
],
"pagination": {
"limit": 1,
"page": 1,
"pages": 2,
"size": 2
}
}
Get a role.
GET WEB_SERVICE_URL/roles/{role_id}
With {role_id} the id of the role to retrieve.
Name | Type | Required | Default | Details |
---|---|---|---|---|
include | Array | No | - | The list of fields to include from returned role |
exclude | Array | No | - | The list of fields to exclude from returned role. Ignored if include is also specified |
HTTP Status Code | Details |
---|---|
200 | Got the role |
500 | An error occured on the server side |
400 | Missing the id of the role |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
404 | Role not found |
{
"entity": {
"id": "{role_id}",
"name": "Role name",
"permissions" : [...]
}
}
Add roles.
PUT WEB_SERVICE_URL/roles
Expects an Array of objects containing:
Name | Type | Required | Default | Details |
---|---|---|---|---|
name | String | Yes | - | The role name |
permissions | Array | Yes | - | The role permssions |
HTTP Status Code | Details |
---|---|
200 | The roles have been added |
500 | An error occured on the server side |
400 | Missing body |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities": [
{
"id": "41U3sYipg",
"name": "Role name",
"permissions" : [...]
},
...
],
"total": 42
}
Update a role.
POST WEB_SERVICE_URL/roles/{role_id}
With {role_id} the id of the role to update.
Name | Type | Required | Default | Details |
---|---|---|---|---|
name | String | No | - | The role name |
permissions | Array | No | - | The role permssions |
HTTP Status Code | Details |
---|---|
200 | The role has been updated |
500 | An error occured on the server side |
400 | Missing the role id or the body |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 1
}
Delete roles.
DELETE WEB_SERVICE_URL/roles/{role_id}
With {role_id} a comma separated list of role ids to delete.
HTTP Status Code | Details |
---|---|
200 | The roles have been deleted |
500 | An error occured on the server side |
400 | Missing the role ids |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 42
}
Users
Get users.
GET WEB_SERVICE_URL/users
Name | Type | Required | Default | Details |
---|---|---|---|---|
query | String | No | - | To search on user names |
origin | String | No | all | The users origin (either cas, ldap, local or all) |
sortBy | String | No | name | The field to use to sort users. Only name is available right now |
sortOrder | String | No | desc | The sort order (either asc or desc) |
page | Number | No | 0 | The expected page |
limit | Number | No | 10 | The limit the number of users per page |
include | Array | No | - | The list of fields to include from returned users |
exclude | Array | No | - | The list of fields to exclude from returned users. Ignored if include is also specified |
HTTP Status Code | Details |
---|---|
200 | Got the list of users |
500 | An error occured on the server side |
400 | Wrong list of parameters |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities": [
{
"id": "42",
"name": "User name",
"email": "user.mail@company.com",
"origin": "local",
"locked": false,
"roles": ["role1"]
}
],
"pagination": {
"limit": 1,
"page": 1,
"pages": 2,
"size": 2
}
}
Get a user.
GET WEB_SERVICE_URL/users/{user_id}
With {user_id} the id of the user to retrieve.
Name | Type | Required | Default | Details |
---|---|---|---|---|
include | Array | No | - | The list of fields to include from returned user |
exclude | Array | No | - | The list of fields to exclude from returned user. Ignored if include is also specified |
HTTP Status Code | Details |
---|---|
200 | Got the user |
500 | An error occured on the server side |
400 | Missing the id of the user |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
404 | User not found |
{
"entity": {
"id": "{user_id}",
"name": "User name",
"password": "38d03dd58cd1bb6b4fdc59c3d03601461118c166b48baf787b96d5589ff0758d",
"email": "user.mail@company.com",
"origin": "local",
"locked": false,
"roles": ["role1"]
}
}
Add users.
PUT WEB_SERVICE_URL/users
Expects an Array of objects containing:
Name | Type | Required | Default | Details |
---|---|---|---|---|
name | String | Yes | - | The user name |
String | Yes | - | The user email | |
password | String | Yes | - | The user password |
passwordValidate | String | Yes | - | The user password validation |
roles | Array | No | - | To user roles |
locked | Boolean | No | - | To lock the user from edition |
HTTP Status Code | Details |
---|---|
200 | The users have been added |
500 | An error occured on the server side |
400 | Missing body |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities": [
{
"id": "41U3sYipg",
"name": "User name",
"password": "38d03dd58cd1bb6b4fdc59c3d03601461118c166b48baf787b96d5589ff0758d",
"email": "user.mail@company.com",
"origin": "local",
"locked": false,
"roles": ["role1"]
},
...
],
"total": 42
}
Update a user.
POST WEB_SERVICE_URL/users/{user_id}
With {user_id} the id of the user to update.
Name | Type | Required | Default | Details |
---|---|---|---|---|
name | String | No | - | The user name |
String | No | - | The user email | |
password | String | No | - | The user password |
passwordValidate | String | No | - | The user password validation |
roles | Array | No | - | To user roles |
HTTP Status Code | Details |
---|---|
200 | The user has been updated |
500 | An error occured on the server side |
400 | Missing the user id or the body |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 1
}
Delete users.
DELETE WEB_SERVICE_URL/users/{user_id}
With {user_id} a comma separated list of user ids to delete.
HTTP Status Code | Details |
---|---|
200 | The users have been deleted |
500 | An error occured on the server side |
400 | Missing the user ids |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 42
}
Applications
Get applications.
GET WEB_SERVICE_URL/applications
Name | Type | Required | Default | Details |
---|---|---|---|---|
query | String | No | - | To search on application names |
sortBy | String | No | name | The field to use to sort applications. Only name is available right now |
sortOrder | String | No | desc | The sort order (either asc or desc) |
page | Number | No | 0 | The expected page |
limit | Number | No | 10 | The limit the number of applications per page |
include | Array | No | - | The list of fields to include from returned applications |
exclude | Array | No | - | The list of fields to exclude from returned applications. Ignored if include is also specified |
HTTP Status Code | Details |
---|---|
200 | Got the list of applications |
500 | An error occured on the server side |
400 | Wrong list of parameters |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities": [
{
"id": "4J6CUL_gZ",
"name": "Application name",
"scopes": [...],
"secret" : "179a905785d4258bba255ffb812a25f2225f7d4c"
}
],
"pagination": {
"limit": 1,
"page": 1,
"pages": 2,
"size": 2
}
}
Get an application.
GET WEB_SERVICE_URL/applications/{application_id}
With {application_id} the id of the application to retrieve.
Name | Type | Required | Default | Details |
---|---|---|---|---|
include | Array | No | - | The list of fields to include from returned application |
exclude | Array | No | - | The list of fields to exclude from returned application. Ignored if include is also specified |
HTTP Status Code | Details |
---|---|
200 | Got the application |
500 | An error occured on the server side |
400 | Missing the id of the application |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
404 | Application not found |
{
"entity": {
"id": "{application_id}",
"name": "Application name",
"scopes": [...],
"secret" : "179a905785d4258bba255ffb812a25f2225f7d4c"
}
}
Add applications.
PUT WEB_SERVICE_URL/applications
Expects an Array of objects containing:
Name | Type | Required | Default | Details |
---|---|---|---|---|
name | String | Yes | - | The application name |
scopes | Array | No | - | The application scopes |
HTTP Status Code | Details |
---|---|
200 | The applications have been added |
500 | An error occured on the server side |
400 | Missing the body |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities": [
{
"id": "41U3sYipg",
"name": "Application name",
"scopes": [...],
"secret": "179a905785d4258bba255ffb812a25f2225f7d4c"
},
...
],
"total": 42
}
Update an application.
POST WEB_SERVICE_URL/applications/{application_id}
With {application_id} the id of the application to update.
Name | Type | Required | Default | Details |
---|---|---|---|---|
name | String | No | - | The application name |
scopes | Array | No | - | The application scopes |
HTTP Status Code | Details |
---|---|
200 | The application has been updated |
500 | An error occured on the server side |
400 | Missing the application id or the body |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 1
}
Delete applications.
DELETE WEB_SERVICE_URL/applications/{application_id}
With {application_id} a comma separated list of application ids to delete.
HTTP Status Code | Details |
---|---|
200 | The applications have been deleted |
500 | An error occured on the server side |
400 | Missing the application ids |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 42
}
Settings
Get settings.
GET WEB_SERVICE_URL/settings
Name | Type | Required | Default | Details |
---|---|---|---|---|
sortOrder | String | No | desc | The sort order (either asc or desc) |
page | Number | No | 0 | The expected page |
limit | Number | No | 10 | The limit the number of settings per page |
HTTP Status Code | Details |
---|---|
200 | Got the list of settings |
500 | An error occured on the server side |
400 | Wrong list of parameters |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities": [
{
"id": "my-setting",
"value": "Mixed value"
}
],
"pagination": {
"limit": 1,
"page": 1,
"pages": 2,
"size": 2
}
}
Get a setting.
GET WEB_SERVICE_URL/settings/{setting_id}
With {setting_id} the id of the setting to retrieve.
HTTP Status Code | Details |
---|---|
200 | Got the setting |
500 | An error occured on the server side |
400 | Missing the id of the setting |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entity": {
"id": "my-setting",
"value": "Mixed value"
}
}
Add settings.
If a setting already exists it will be updated.
PUT WEB_SERVICE_URL/settings
Expects an Array of objects containing:
Name | Type | Required | Default | Details |
---|---|---|---|---|
id | String | Yes | - | The setting id |
value | Mixed | Yes | - | The setting value |
HTTP Status Code | Details |
---|---|
200 | The settings have been added |
500 | An error occured on the server side |
400 | Missing setting ids in body |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities": [
{
"id": "my-setting",
"value": "Mixed value"
},
...
],
"total": 42
}
Update a setting.
POST WEB_SERVICE_URL/settings/{setting_id}
With {setting_id} the id of the setting to update.
Name | Type | Required | Default | Details |
---|---|---|---|---|
value | Mixed | No | - | The setting value |
HTTP Status Code | Details |
---|---|
200 | The setting has been updated |
500 | An error occured on the server side |
400 | Missing the setting id or the body |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 1
}
Delete settings.
DELETE WEB_SERVICE_URL/settings/{setting_id}
With {setting_id} a comma separated list of setting ids to delete.
HTTP Status Code | Details |
---|---|
200 | The settings have been deleted |
500 | An error occured on the server side |
400 | Missing the setting id |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 42
}
Client libraries
PHP client
A PHP client is also available on Github to help interface with OpenVeo Web Service.
NodeJS client
A NodeJS client is also available on Github to help interface with OpenVeo Web Service.