Roles
Get list of roles
Description
This endpoint returns a list of all roles existing on the specified domain. In the case of an administrator, a list containing all roles will be returned. For other roles, this will generally only include their own role account.
Request
GET /liveforms/api/domains/{domain}/roles
parameter |
description |
---|---|
domain |
The name of a valid domain which the authenticated role has access to. |
Response
Possible HTTP response codes:
Code |
Description |
---|---|
200 OK |
Success |
401 UNAUTHORIZED |
The rolename/password used for authentication was invalid. |
403 FORBIDDEN |
The authenticated role does not have permission to access this domain. |
404 NOT FOUND |
The domain does not exist. |
500 SERVER ERROR |
The request failed due to an internal server error. |
If the request is successful, a JSON (default) or XML payload will be returned containing the requested information.
Example JSON response
{
"title": "Roles",
"link": {
"rel": "self",
"href": "/liveforms/api/domains/demo/roles"
},
"entry": [{
"id": "1",
"name": "role1",
"description": "Role 1",
"link": [{
"rel": "self",
"href": "/liveforms/api/domains/demo/roles/role1"
}]
}]
}
Example XML response
<?xml version="1.0" encoding="UTF-8"?>
<feed>
<title>Roles</title>
<link rel="self" href="/liveforms/api/domains/demo/roles"/>
<entry>
<id>1</id>
<name>role1</name>
<description>Role 1</description>
<link rel="self" href="/liveforms/api/domains/demo/roles/role1"/>
</entry>
</feed>
Get role by name
Description
This endpoint returns information representing the requested role provided the authenticated role has access to it.
Request
GET /liveforms/api/domains/{domain}/roles/{role}
parameter |
description |
---|---|
domain |
The name of a domain |
role |
The name of a role existing on the domain |
Response
Possible HTTP response codes:
Code |
Description |
---|---|
200 OK |
Success |
401 UNAUTHORIZED |
The rolename/password used for authentication was invalid. |
403 FORBIDDEN |
The authenticated role does not have permission to access this role. |
404 NOT FOUND |
The role does not exist on this domain |
500 SERVER ERROR |
The request failed due to an internal server error. |
If the request is successful, a JSON (default) or XML payload will be returned containing the requested information.
Example JSON response
{
"id": "1",
"name": "role1",
"description": "Role 1",
"link": [{
"rel": "self",
"href": "/liveforms/api/domains/demo/roles/role1"
}]
}
Example XML response
<?xml version="1.0" encoding="UTF-8"?>
<entry>
<id>1</id>
<name>role1</name>
<description>Demo</description>
<link rel="self" href="/liveforms/api/domains/demo/roles/role1"/>
</entry>
Create role
Description
This endpoint accepts information on creating a new role. The request payload should include a JSON or XML description of the role to be created (see below for examples).
Request
POST /liveforms/api/domains/{domain}/roles
parameter |
description |
---|---|
domain |
The name of a domain |
Example JSON request
{
"name": "role1",
"description": "Role 1",
}
Example XML request
<?xml version="1.0" encoding="UTF-8"?>
<entry>
<name>role1</name>
<description>Role 1</description>
</entry>
Response
Possible HTTP response codes:
Code |
Description |
---|---|
201 CREATED |
Success |
401 UNAUTHORIZED |
The rolename/password used for authentication was invalid. |
403 FORBIDDEN |
The authenticated role does not have permission to create roles on this domain. |
409 CONFLICT |
The role could not be created, likely because another already exists in the domain with the specified name. |
500 SERVER ERROR |
The request failed due to an internal server error. |
If the request is successful, a JSON (default) or XML payload will be returned containing information on the created role.
Example JSON response
{
"id": "1",
"name": "role1",
"description": "Role 1",
"link": [{
"rel": "self",
"href": "/liveforms/api/domains/demo/roles/role1"
}]
}
Example XML response
<?xml version="1.0" encoding="UTF-8"?>
<entry>
<id>1</id>
<name>role1</name>
<description>Demo</description>
<link rel="self" href="/liveforms/api/domains/demo/roles/role1"/>
</entry>
Update role
Description
This endpoint accepts information on updating an existing role. The request payload should include a JSON or XML description of the updated role information (see below for examples).
Note
It is possible to rename roles with this request. The name of the role referenced by the URL should be the current name, while the request payload should specifiy the new name.
Note
The fields shown in the example request payload are optional. If a field is omitted, that property of the role will not be modified by the request.
Request
PUT /liveforms/api/domains/{domain}/roles/{role}
parameter |
description |
---|---|
domain |
The name of a domain |
role |
The name of the role to be updated |
Example JSON request
{
"name": "role1",
"description": "Role 1",
}
Example XML request
<?xml version="1.0" encoding="UTF-8"?>
<entry>
<name>role1</name>
<description>Role 1</description>
</entry>
Response
Possible HTTP response codes:
Code |
Description |
---|---|
200 OK |
Success |
401 UNAUTHORIZED |
The rolename/password used for authentication was invalid. |
403 FORBIDDEN |
The authenticated role does not have permission to modify roles on this domain. |
404 NOT FOUND |
The role to be updated could not be found. |
500 SERVER ERROR |
The request failed due to an internal server error. |
If the request is successful, a JSON (default) or XML payload will be returned containing updated information on the role.
Example JSON response
{
"id": "1",
"name": "role1",
"description": "Role 1",
"link": [{
"rel": "self",
"href": "/liveforms/api/domains/demo/roles/role1"
}]
}
Example XML response
<?xml version="1.0" encoding="UTF-8"?>
<entry>
<id>1</id>
<name>role1</name>
<description>Demo</description>
<link rel="self" href="/liveforms/api/domains/demo/roles/role1"/>
</entry>
Delete role
Description
This endpoint accepts requests to delete a role. There is no payload body associated with this request.
Request
DELETE /liveforms/api/domains/{domain}/roles/{role}
parameter |
description |
---|---|
domain |
The name of a domain |
role |
The name of the role to be updated |
Response
Possible HTTP response codes:
Code |
Description |
---|---|
200 OK |
Success |
401 UNAUTHORIZED |
The rolename/password used for authentication was invalid. |
403 FORBIDDEN |
The authenticated role does not have permission to delete roles on this domain. |
404 NOT FOUND |
The role to be deleted could not be found. |
500 SERVER ERROR |
The request failed due to an internal server error. |
If the request is successful, the response will contain the ID of the deleted role.
Example JSON response
{
"id": "1",
}
Example XML response
<?xml version="1.0" encoding="UTF-8"?>
<entry>
<id>1</id>
</entry>