Roles¶

Important

The API is a work in progress. GET requests have been implemented in the current version, but POST, UPDATE, and DELETE support is not yet complete.

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>