Note: See OpenAPI documentation available in Obeo Designer Team Administration Server - OpenAPI.
This guide describe the REST API of the administration server for Obeo Designer Team Server. This API will allow you to manage CDO repositories, shared modeling projects and depending on the type of repository you manage, you will be able to manager the repository users. If you already have configured the administration server for Obeo Designer Team Server you can start to use our API.
Remark: The protocol, host and port can be different from your server configuration.
In this documentation we will use the web service API in the version v1.0.
Disclaimer: As basic authentication is enabled for the administration server, the Authorization header must be added in all requests with the base64 encoded credentials.
This section describes the API to create, delete, start, stop your repositories, to export a backup of the repository database and to import a backup into the database.
As the repository creation is the main feature of this API we provide many examples of how to create a repository.
This request will allow you to creates a repository.
The body of the request take a JSON object with the following parameters:
repositoryName, authenticationType and
datasourceType which are mandatory and also
authenticationData and
datasourceData which are optional.
While the
authenticationType value can be empty, the
repositoryName and the
datasourceType values cannot.
By default you can use the following values to manage your repositories:
You can also contribute your own extensions and use the key value of you extension as describe in the administration server of Obeo Designer team Server documentation.
Those values describe how your repository will manage authentication and database.
As the optional parameters ( authenticationData and datasourceData) depends on the mandatory parameters, we will use examples to describe how to use them.
This example will create a repository without authentication with an H2 embedded database.
The body of the request:
{
"repositoryName": "repository-without-authentication",
"authenticationType": "",
"datasourceType": "H2_EMBEDDED"
}
With an empty value set to authenticationType your repository will not have authentication. With H2_EMBEDDED value set to datasourceType your repository database will be an h2 embedded database.
The repository is started after it is created and life cycle hooks are called before and after its start.
The body of the response will be:
{
"message": "The repository repository-without-authentication has been created.",
"status": 201,
"repository": {
"name": "repository-without-authentication"
}
}
This example will create a repository without authentication on H2 server database.
The body of the request:
{
"repositoryName": "repository-without-authentication",
"authenticationType": "",
"datasourceType": "H2_SERVER",
"datasourceData": {
"h2ServerPort": "9092"
}
}
With an empty value set to authenticationType your repository will not have authentication. With H2_SERVER value set to datasourceType your repository database will be an h2 server database and you will need to provide additional data like the h2ServerPort within the datasourceData map. The h2ServerPort is used in the connection between the repository and the h2 database. The h2ServerPort value must be a string.
The repository is started after it is created and life cycle hooks are called before and after its start.
Disclaimer
If your repository is configured with an h2 server database, we use the IP address of the current machine to set up the h2 server before it starts.
The attribute «port» of datasourceData has been deprecated in favor of «h2ServerPort». This changes has been made to avoid confusion with the port used to connect to the repository.
The body of the response will be:
{
"message": "The repository repository-without-authentication has been created.",
"status": 201,
"repository": {
"name": "repository-without-authentication"
}
}
This example will create a repository with LDAP authentication on H2 embedded database.
The body of the request:
{
"repositoryName": "repository-with-ldap",
"authenticationType": "LDAP",
"authenticationData": {
"url": "ldap://localhost:10389",
"dnPattern": "cn={user},ou=people,o=sevenSeas"
},
"datasourceType": "H2_EMBEDDED"
}
With LDAP value set to authenticationType, your repository will use LDAP to authenticate users who have the right to modify the repository. You will need to provide within the authenticationData map the same data described in the Configure LDAP section of the Administrator manual available in the integrated help of Obeo Designer Team Edition, namely:
The repository is started after it is created and life cycle hooks are called before and after its start.
The body of the response will be:
{
"message": "The repository repository-with-ldap has been created.",
"status": 201,
"repository": {
"name": "repository-with-ldap"
}
}
Note
An H2 server database can be used instead of an h2 embedded database. Go to this section to see how to create a repository with an H2 server database.
This example will create a repository with User manager authentication on H2 embedded database.
The body of the request:
{
"repositoryName": "repository-with-file",
"authenticationType": "FILE",
"authenticationData": {
"users": [
{
"login": "Horatio Nelson",
"password": "pass"
}
]
},
"datasourceType": "H2_EMBEDDED"
}
With FILE value set to the authenticationType, your repository will use the user manager to authorize registered user to modify the repository. You will need to provide within the authenticationData map a list of users used to populate the users.properties file as described in the Authenticated Configuration section of the Administrator manual available in the integrated help of Obeo Designer Team Edition. The list of users is an array of map containing at least the login and password keys.
The repository is started after it is created and life cycle hooks are called before and after its start.
The body of the response will be:
{
"message": "The repository repository-with-file has been created.",
"status": 201,
"repository": {
"name": "repository-with-file"
}
}
Note
An H2 server database can be used instead of an h2 embedded database. Go to this section to see how to create a repository with an H2 server database.
This example will create a repository with user manager and LDAP authentication on H2 embedded database.
The body of the request:
{
"repositoryName": "repository-with-file-ldap",
"authenticationType": "LDAP_FILE",
"authenticationData": {
"url": "ldap://localhost:10389",
"dnPattern": "cn={user},ou=people,o=sevenSeas",
"users": [
{
"login": "Horatio Nelson"
}
]
},
"datasourceType": "H2_EMBEDDED"
}
With LDAP_FILE value set to authenticationType, your repository will use the user manager to register to authorize registered user to modify the repository and use LDAP to authenticate them. You will need to provide within the authenticationData map a list of users used to populate the users.properties file and also additional data to handle LDAP as described in the Configure LDAP section of the Administrator manual available in the integrated help of Obeo Designer Team Edition.
The list of users is an array of map containing at least the login keys. The additional data needed to handle LDAP are :
The repository is started after it is created and life cycle hooks are called before and after its start.
The body of the response will be:
{
"message": "The repository repository-with-file-ldap has been created.",
"status": 201,
"repository": {
"name": "repository-with-file-ldap"
}
}
Note
An H2 server database can be used instead of an h2 embedded database. Go to this section to see how to create a repository with an H2 server database.
This example will create a repository with user profile authentication on H2 embedded database.
The body of the request:
{
"repositoryName": "repository-with-userprofile",
"authenticationType": "USERPROFILE",
"authenticationData": {
"administrators": [
{
"login": "Horatio Nelson",
"password": "pass"
}
]
},
"datasourceType": "H2_EMBEDDED"
}
With USERPROFILE value set to the authenticationType, your repository will use the user profile to manage authorization on your repository. You will need to provide within the authenticationData map a list of administrators used to populate the user profile model with users who have the write right on the repository as described in the User Profile Configuration section of the Administrator manual available in the integrated help of Obeo Designer Team Edition. The list of administrators is an array of map containing at least the login and password keys.
The repository is started after it is created and life cycle hooks are called before and after its start.
The body of the response will be:
{
"message": "The repository repository-with-userprofile has been created.",
"status": 201,
"repository": {
"name": "repository-with-userprofile"
}
}
Note
An H2 server database can be used instead of an h2 embedded database. Go to this section to see how to create a repository with an H2 server database.
This example will create a repository with user profile and LDAP authentication on H2 embedded database.
The body of the request:
{
"repositoryName": "repository-with-userprofile-ldap",
"authenticationType": "LDAP_USERPROFILE",
"authenticationData": {
"url": "ldap://localhost:10389",
"dnPattern": "cn={user},ou=people,o=sevenSeas",
"administrators": [
{
"login": "Horatio Nelson"
}
]
},
"datasourceType": "H2_EMBEDDED"
}
With LDAP_USERPROFILE value set to the authenticationType, your repository will use the user profile to manage authorization on your repository. You will need to provide within the authenticationData map a list of administrators used to populate the user profile model with users who have the write right on the repository and also additional data to handle LDAP as described in the Configure LDAP section of the Administrator manual available in the integrated help of Obeo Designer Team Edition.
The list of administrators is an array of map containing at least the login key. The additional data needed to handle LDAP are :
The repository is started after it is created and life cycle hooks are called before and after its start.
The body of the response will be:
{
"message": "The repository repository-with-userprofile-ldap has been created.",
"status": 201,
"repository": {
"name": "repository-with-userprofile-ldap"
}
}
Note
An H2 server database can be used instead of an h2 embedded database. Go to this section to see how to create a repository with an H2 server database.
The above responses are returned if everything goes well. It may be possible parameters given to the web service are not valid or an error can simply happen. In those cases an error message that explain the cause of the error is returned:
{
"message": "The repository repository-with-userprofile-ldap has not been created.",
"status": 400,
"error": "The url to the ldap server is empty."
}
{
"message": "The repository repository-with-userprofile-ldap has not been created.",
"status": 500,
"error": "An error occurred during the repository configuration: The h2 server was not able to start.\nException: ...."
}
This request will allow you to retrieve all repositories that were created using the web service to create a repository.
The body of the response can be:
{
"message": "All available repositories",
"status": 200,
"repositories": [
{
"name": "repository-without-authentication",
"status": "ONLINE"
},
{
"name": "repository-with-file-ldap",
"status": "OFFLINE"
}
]
}
{
"message": "An error occurred.",
"status": 500,
"error": "...."
}
This request will allow you to delete a repository that was created using the web service to create a repository.
The delete removes the folder and all of its content in the directory that contains the repositories. This directory can be configured in the properties files of the administration server as describe in the
configuration of the administration server.
The body of the response can be:
{
"message": "The repository repository-without-authentication has been completely deleted.",
"status": 200,
"repository": {
"name": "repository repository-without-authentication"
},
"isDatabaseDeleted": true
}
{
"message": "The repository has not been deleted.",
"status": 400,
"error": "The repository name is empty."
}
{
"message": "The repository repository-without-authentication has not been deleted.",
"status": 404,
"error": "The repository repository-without-authentication has not been found."
}
{
"message": "The repository repository-without-authentication has not been deleted.",
"status": 500,
"error": "Something happens during the repository deletion: ..."
}
This request will allow you to start a repository that was created using the web service to create a repository. The life cycle hooks will be called before and after its start.
The body of the response can be:
{
"message": "The repository repository-with-userprofile is running.",
"status": 200,
"repository": {
"name": "repository-with-userprofile"
}
}
{
"message": "The repository repository-with-userprofile has not been started.",
"status": 400,
"error": "The repository repository-with-userprofile is not stopped."
}
{
"message": "The repository repository-with-userprofile has not been started.",
"status": 404,
"error": "The repository repository repository-with-userprofile has not been found."
}
{
"message": "The repository repository-with-userprofile has not been started.",
"status": 500,
"error": "An error occurred while starting the repository: ..."
}
This request will allow you to stop a repository that was created using the web service to create a repository. The life cycle hooks will be called before and after its stop.
The body of the response can be:
{
"message": "The repository repository-with-userprofile has been stopped.",
"status": 200,
"repository": {
"name": "repository-with-userprofile"
}
}
{
"message": "The repository repository-with-userprofile has not been stopped.",
"status": 400,
"error": "The repository repository-with-userprofile is not started."
}
{
"message": "The repository repository-with-userprofile has not been stopped.",
"status": 404,
"error": "The repository repository repository-with-userprofile has not been found."
}
{
"message": "The repository repository-with-userprofile has not been stopped.",
"status": 500,
"error": "An error occurred while stopping the repository: ..."
}
This request will allow you to export the database of the repository into an xml file. The body of the request take two parameters: needsEncryption which is mandatory and password which is optional but needed if needsEncryption is set to true.
As the export of the database can take time, the web service will schedule an asynchronous job and return the link where you will be able to download the file in the response under the url attribute.
If needsEncryption is set to false the export of the database will create an xml file representing the cdo database in the export folder which can be configured in the properties files of the administration server as describe in the configuration of the administration server. If needsEncryption is set to true the an encrypted zip file containing the xml file will be created instead.
This example will export the database of the repository «repository-with-userprofile» into an encrypted zip file.
The body of the request:
{
"needsEncryption": true,
"password": "password"
}
The body of the response can be:
{
"message": "The export for the repository repository-with-userprofile as been launched. You will be able to retrieved the exported data at the url: http://localhost:8080/export/path/to/the/zipfile.zip",
"status": 200,
"url": "http://localhost:8080/export/path/to/the/zipfile.zip",
"repository": "repository-with-userprofile"
}
{
"message": "The repository repository-with-userprofile will not be exported.",
"status": 400,
"error": "The export encryption has been requested but no password has been provided."
}
{
"message": "The repository repository-with-userprofile will not be exported.",
"status": 404,
"error": "The repository repository-with-userprofile has not been found."
}
{
"message": "An error occurred.",
"status": 500,
"error": "..."
}
this request will allow you to upload an xml file which must be a backup of the database. As this API needs a file, we suggest you to use the input file of your favorite browser in order to let it set the correct headers for the upload of the file.
As the import of the database can take time, the web service will schedule an asynchronous job.
The state of the repository will be the same after the import as before the import.
This example will upload an xml file and will import it in the database of the repository «repository-with-userprofile».
The body of the response can be:
{
"message": "The data are being imported to the repository repository-with-userprofile. The state of the repository will be the same after and before the import.",
"status": 200,
"repository": "repository-with-userprofile"
}
{
"message": "The import of the repository repository-with-userprofile will not be launched.",
"status": 400,
"error": "The import will not be executed because some connections remains (alice, bob)"
}
{
"message": "The import of the repository repository-with-userprofile will not be launched.",
"status": 404,
"error": "The repository repository-with-userprofile has not been found."
}
{
"message": "An error occurred.",
"status": 500,
"error": "..."
}
This section describes the API to create your shared modeling projects.
This request will allow you to create an empty shared modeling project. The repository where you want to create the shared modeling project should be started.
The post created project life cycle hook will be called after the project is created. For example, the user profile extension life cycle hook will create roles for users. The name of the created role will have the project name and will authorize a user to create, read, update and delete resources inside the project.
This example will create the shared modeling project named «Awesome-project» in the repository named «repository-with-userprofile».
As this repository uses the user profile to authenticate its users, the post created project life cycle hook will create roles that will give write access to users for the project.
The body of the request:
{
"projectName": "Awesome-project",
"repositoryName": "repository-with-userprofile"
}
The body of the response can be:
{
"message": "The project Awesome-project has been successfully created in the repository repository-with-userprofile.",
"status": 201,
"projectName": "Awesome-project"
}
{
"message": "The project has not been created",
"status": 400,
"error": "The repository repository-with-user-profile is not started"
}
{
"message": "The project has not been created",
"status": 500,
"error": "Something happens while creating the shared modeling project: ..."
}
This section describes the API to create, delete, list and modify users on a repository.
This request will allow you to create a user in the repository.
The body of the request take a JSON object with the following parameters:
id,
isAdministrator,
password and
permissions. The
id and
isAdministrator are mandatory. The
password can be avoid if the repository authentication is managed with LDAP. The
permissions parameter is used for repositories with authorization managed with user profiles. This parameter is an array of project name which will be used to grant writing rights to the user for those projects.
This example will create the user «John Fryer» in the repository named «repository-with-userprofile». As authentication is not managed with LDAP we should provide a password. We don’t want «John Fryer» to be an administrator and we want give him the writing rights to the «Awesome-project» project.
The body of the request:
{
"id": "John Fryer",
"password": "password",
"isAdministrator": false,
"permissions": [
"Awesome-project"
]
}
The body of the response can be:
{
"message": "The user John Fryer has been created in the repository repository-with-userprofile with the permissions [Awesome-project].",
"status": 201,
"user": {
"id": "John Fryer",
"isAdministrator": false,
"permissions": [
"Awesome-project"
]
},
"repositoryName": "repository-with-userprofile",
"projectNames": [
"Awesome-project"
]
}
{
"message": "The user John Fryer cannot be created",
"status": 400,
"error": "The list of administrators is empty."
}
{
"message": "The user John Fryer cannot be created",
"status": 500,
"error": "An error occurred while creating the user: ..."
}
This request will allow you to retrieve the list of user of a repository.
The body of the response can be:
{
"message": "The list of users for the repository repository-with-userprofile.",
"status": 200,
"repositoryName": "repository-with-userprofile",
"users": [
{
"id": "John Fryer",
"isAdministrator": false,
"permissions": [
"Awesome-project"
]
}
]
}
{
"message": "Users cannot be listed on repository repository-with-userprofile.",
"status": 400,
"error": "The repository repository-with-userprofile has not been found."
}
{
"message": "An error occurred.",
"status": 500,
"error": "..."
}
This request will allow you to update user data.
As the behavior of the update of the user will delete then create the user with the new data, The body of the request take the same parameters as the body of the request that create users.
This example will update the password of «John Fryer».
The body of the request:
{
"id": "John Fryer",
"password": "pass",
"isAdministrator": false,
"permissions": [
"Awesome-project"
]
}
The body of the response can be:
{
"message": "The user John Fryer has been updated in the repository repository-with-userprofile.",
"status": 201,
"user": {
"id": "John Fryer",
"isAdministrator": false,
"permissions": [
"Awesome-project"
]
},
"repositoryName": "repository-with-userprofile"
}
{
"message": "The user John Fryer has not been updated in the repository repository-with-userprofile.",
"status": 400,
"error": "Administrators must be a collection of administrators."
}
{
"message": "The user John Fryer has not been updated in the repository repository-with-userprofile.",
"status": 404,
"error": "The user John Fryer has not been found in the repository repository-with-userprofile."
}
{
"message": "The user John Fryer has not been updated in the repository repository-with-userprofile.",
"status": 500,
"error": "An error occurred while updating the user: ..."
}
This request will allow you to delete a user from a repository.
This example will delete the user «John Fryer» from the repository named «repository-with-userprofile».
The body of the response can be:
{
"message": "The user John Fryer has been deleted from the repository repository-with-userprofile.",
"status": 200,
"repositoryName": "repository-with-userprofile"
}
{
"message": "The user John Fryer has not been deleted from the repository repository-with-userprofile.",
"status": 400,
"error": "The repository repository-with-userprofile has not been found."
}
{
"message": "The user John Fryer has not been deleted from the repository repository-with-userprofile.",
"status": 404,
"error": "The user John Fryer has not been found in the repository repository-with-userprofile."
}
{
"message": "The user John Fryer has not been deleted from the repository repository-with-userprofile.",
"status": 500,
"error": "An error occurred while deleting the user: ..."
}
In this section we took the request to create a user in a repository with authorization managed with user profile.
In the following examples the
Authorization header value is took from the administration server configuration sample in the
realm.properties file and correspond to the base64 encoded value of the
sampleuser credentials.
The body of the request:
{
"id": "John Fryer",
"password": "password",
"isAdministrator": false,
"permissions": [
"Awesome-project"
]
}
curl --request POST \
--url 'http://localhost:8080/api/v1.0/users?repositoryName=repository-with-userprofile' \
--header 'Authorization: Basic c2FtcGxldXNlcjpzYW1wbGVwYXNzd29yZA==' \
--header 'Content-Type: application/json' \
--data '{
"id": "John Fryer",
"password": "password",
"isAdministrator": false,
"permissions": [
"Awesome-project"
]
}'
var settings = {
"async": true,
"crossDomain": true,
"url": "http://localhost:8080/api/v1.0/users?repositoryName=repository-with-userprofile",
"method": "POST",
"headers": {
"Authorization": "Basic c2FtcGxldXNlcjpzYW1wbGVwYXNzd29yZA==",
"Content-Type": "application/json"
},
"processData": false,
"data": "{\n \"id\": \"John Fryer\",\n \"password\": \"password\",\n \"isAdministrator\": false,\n \"permissions\": [\n\t\"Awesome-project\"\n ]\n}"
}
$.ajax(settings).done(function (response) {
console.log(response);
});
require 'uri'
require 'net/http'
url = URI("http://localhost:8080/api/v1.0/users?repositoryName=repository-with-userprofile")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic c2FtcGxldXNlcjpzYW1wbGVwYXNzd29yZA=='
request["Content-Type"] = 'application/json'
request.body = "{\n \"id\": \"John Fryer\",\n \"password\": \"password\",\n \"isAdministrator\": false,\n \"permissions\": [\n\t\"Awesome-project\"\n ]\n}"
response = http.request(request)
puts response.read_body
import requests
url = "http://localhost:8080/api/v1.0/users"
querystring = {"repositoryName":"repository-with-userprofile"}
payload = "{\n \"id\": \"John Fryer\",\n \"password\": \"password\",\n \"isAdministrator\": false,\n \"permissions\": [\n\t\"Awesome-project\"\n ]\n}"
headers = {
'Authorization': "Basic c2FtcGxldXNlcjpzYW1wbGVwYXNzd29yZA==",
'Content-Type': "application/json"
}
response = requests.request("POST", url, data=payload, headers=headers, params=querystring)
print(response.text)
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"localhost"
],
"port": "8080",
"path": [
"api",
"v1.0",
"users"
],
"headers": {
"Authorization": "Basic c2FtcGxldXNlcjpzYW1wbGVwYXNzd29yZA==",
"Content-Type": "application/json"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ id: 'John Fryer',
password: 'password',
isAdministrator: false,
permissions: [ 'Awesome-project' ] }));
req.end();
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_PORT => "8080",
CURLOPT_URL => "http://localhost:8080/api/v1.0/users?repositoryName=repository-with-userprofile",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\n \"id\": \"John Fryer\",\n \"password\": \"password\",\n \"isAdministrator\": false,\n \"permissions\": [\n\t\"Awesome-project\"\n ]\n}",
CURLOPT_HTTPHEADER => array(
"Authorization: Basic c2FtcGxldXNlcjpzYW1wbGVwYXNzd29yZA==",
"Content-Type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "http://localhost:8080/api/v1.0/users?repositoryName=repository-with-userprofile"
payload := strings.NewReader("{\n \"id\": \"John Fryer\",\n \"password\": \"password\",\n \"isAdministrator\": false,\n \"permissions\": [\n\t\"Awesome-project\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic c2FtcGxldXNlcjpzYW1wbGVwYXNzd29yZA==")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}