:bulb: This description is valid for v0.5.0 and above.

Introduction

We are defining here the complete set of the actions allowed by the API of the engineManageDomains Servlet. This API is based on the engine-manage-domains CLI.

:fast_forward: Fast Access

List	Add	Delete	Edit

Available actions:

HTTP Methods	URI	Description
GET	/domains	list all the domains
PUT	/domains/{domain-name}	add the new domain {domain-name}
DELETE	/domains/{domain-name}	delete the domain {domain-name}
PUT	/domains/{domain-name}/edit	edit the domain {domain-name}

List :top:

HTTP Methods	URI	Output
GET	/domains	return a collection of JSON objects containing the name and the user of each domains.

This function uses the command list (cf. CLI Documentation).

Response

HTTP Status Code	Description
200 OK	Everything went well. (cf. Description of a Successful Response)
204 No Content	Everything went well but there is no domain to return.
500 Internal Server Error	An error occurs and the command was not able to complete properly.

Description of a Successful Response

Field	Description
domain	Name of the domain
username	User assigned to the domain

Example

----Request----
GET /domains/list

----Answer----
200 OK
{
   "domain": domain1,
   "username": usename@domain1
},
{
   "domain": domain2,
   "username": usename@domain2
}

Add :top:

HTTP Methods	URI	Output
PUT	/domains/{domain-name}	create {domain-name} and return a 201 HTTP status code if it is successful.

This function uses the command add (cf. CLI Documentation).

Creating a Request

To give all the needed information, PUT /domains/{domain-name} must be send with a JSON object containing all the following fields:

Field	Type	Default State	Description
domain	URL/IP	Required	The domain to add.
provider	Abbr.¹	Required	The LDAP provider type¹ of server used for the domain.
user	String	Required	The domain user.
password	String	Required²	The password to manage the domain.
addPermissions	boolean	false	Add engine superuser permissions to the user.
configFile	Absolute Path	""	Use the given alternate configuration file.
ldapServers	String	""	A comma delimited list of LDAP servers to be set to the domain.
resolveKdc	boolean	false	Resolve KDC servers using DNS (don't assume they are the same as LDAP servers).
passwordFile	Absolute Path	Required²	A file containing the password.
¹ The LDAP provider type of server used for the domain, can be one of (case insensitive):

Type	Descripion
ad	Microsoft Active Directory
ipa	freeIPA
rhds	Red Hat Directory Server
itds	IBM Tivoli Directory Server
oldap	OpenLDAP

² You can choose either to send directly the password in the PUT request or to give an absolute path of a file where the password is located.

Response

HTTP Status Code	Meaning
201 Created	Everything went well and the domain has been added successfully.
400 Bad Request	The request was rejected because some informations were missing or not accepted.
500 Internal Server Error	An error occurs and the command was not able to complete properly.

Example

----Request----
PUT /domains/domain1
{
   "domain": "domain1",
   "provider": "ipa",
   "user": "usename@domain1",
   "password": "qwerty123"
   "addPermissions": false,
   "configFile": "",
   "ldapServers": "",
   "resolveKdc": false,
   "passwordFile": ""
}

----Answer----
201 Created
The domain domain1 has been added successfully.

Delete :top:

HTTP Methods	URI	Output
DELETE	/domains/{domain-name}	delete {domain-name} and return a 204 HTTP status code if it is successful.

This function uses the command delete (cf. CLI Documentation).

Response

HTTP Status Code	Meaning
204 No Content	Everything went well and the domain has been deleted successfully.
404 Not Found	The domain {domain-name} doesn't exist in the current configuration.
500 Internal Server Error	An error occurs and the command was not able to complete properly.

Example

----Request----
DELETE /domains/domain1

----Answer----
204 No Content

Edit :top:

HTTP Methods	URI	Output
PUT	/domains/{domain-name}/edit	edit {domain-name} and return a 201 HTTP status code if it is successful.

This function uses the command edit (cf. CLI Documentation).

Creating a Request

To give all the needed information, PUT /domains/{domain-name}/edit must be send with a JSON object containing all the following fields. The function is only going to edit the field which had been modify from their default state.

Field	Type	Default State	Description
domain	URL/IP	Required	The domain to add.
provider	Abbr.¹	""	The LDAP provider type¹ of server used for the domain.
user	String	""	The domain user.
password	String	Required²	The password to manage the domain.
addPermissions	boolean	false	Add engine superuser permissions to the user.
configFile	Absolute Path	""	Use the given alternate configuration file.
ldapServers	String	""	A comma delimited list of LDAP servers to be set to the domain.
resolveKdc	boolean	false	Resolve KDC servers using DNS (don't assume they are the same as LDAP servers).
passwordFile	Absolute Path	Required²	A file containing the password.
¹ The LDAP provider type of server used for the domain, can be one of (case insensitive):

Type	Descripion
ad	Microsoft Active Directory
ipa	freeIPA
rhds	Red Hat Directory Server
itds	IBM Tivoli Directory Server
oldap	OpenLDAP

² You can choose either to send directly the password in the PUT request or to give an absolute path of a file where the password is located.

Response

HTTP Status Code	Meaning
201 Created	Everything went well and the domain has been edited successfully.
400 Bad Request	The request was rejected because some informations were missing or not accepted.
500 Internal Server Error	An error occurs and the command was not able to complete properly.

Example

----Request----
PUT /domains/domain1/edit
{
   "domain": "domain1",
   "provider": "",
   "user": "",
   "password": "qwerty123"
   "addPermissions": false,
   "configFile": "",
   "ldapServers": "",
   "resolveKdc": true,
   "passwordFile": "/usr/share/password.txt"
}

----Answer----
201 Created
The domain domain1 has been edited successfully.