Users¶

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 users¶

Description¶

This endpoint returns a list of all users existing on the specified domain. In the case of an administrator, a list containing all users will be returned. For other users, this will generally only include their own user account.

Request¶

GET /liveforms/api/domains/{domain}/users

parameter	description
domain	The name of a valid domain which the authenticated user has access to.

Response¶

Possible HTTP response codes:

Code	Description
200 OK	Success
401 UNAUTHORIZED	The username/password used for authentication was invalid.
403 FORBIDDEN	The authenticated user 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": "Users",
   "link": {
      "rel": "self",
      "href": "/liveforms/api/domains/demo/users"
   },
   "entry": [{
      "id": "1",
      "name": "user1",
      "first": "Demo",
      "last": "User",
      "email": "user1@example.com",
      "roles": [
         "admin",
         "designer"
      ],
      "link": [{
         "rel": "self",
         "href": "/liveforms/api/domains/demo/users/user1"
      }]
   }]
}

Example XML response

<?xml version="1.0" encoding="UTF-8"?>
<feed>
   <title>Users</title>
   <link rel="self" href="/liveforms/api/domains/demo/users"/>
   <entry>
      <id>1</id>
      <name>user1</name>
      <first>Demo</first>
      <last>User</last>
      <email>user1@example.com</email>
      <roles>
         <role>admin</role>
         <role>designer</role>
      </roles>
      <link rel="self" href="/liveforms/api/domains/demo/users/user1"/>
   </entry>
</feed>

Get user by name¶

Description¶

This endpoint returns information representing the requested user provided the authenticated user has access to it.

Request¶

GET /liveforms/api/domains/{domain}/users/{user}

parameter	description
domain	The name of a domain
user	The name of a user existing on the domain

Response¶

Possible HTTP response codes:

Code	Description
200 OK	Success
401 UNAUTHORIZED	The username/password used for authentication was invalid.
403 FORBIDDEN	The authenticated user does not have permission to access this user.
404 NOT FOUND	The user 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": "user1",
   "first": "Demo",
   "last": "User",
   "email": "user1@example.com",
   "roles": [
      "admin",
      "designer"
   ],
   "link": [{
      "rel": "self",
      "href": "/liveforms/api/domains/demo/users/user1"
   }]
}

Example XML response

<?xml version="1.0" encoding="UTF-8"?>
<entry>
   <id>1</id>
   <name>user1</name>
   <first>Demo</first>
   <last>User</last>
   <email>user1@example.com</email>
   <roles>
      <role>admin</role>
      <role>designer</role>
   </roles>
   <link rel="self" href="/liveforms/api/domains/demo/users/user1"/>
</entry>

Create user¶

Description¶

This endpoint accepts information on creating a new user. The request payload should include a JSON or XML description of the user to be created (see below for examples).

Request¶

POST /liveforms/api/domains/{domain}/users

parameter	description
domain	The name of a domain

Example JSON request

{
   "name": "jdoe",
   "password": "1234",
   "first": "John",
   "last": "Doe",
   "email": "jdoe@example.com",
   "roles": [
      "admin",
      "designer"
   ]
}

Example XML request

<?xml version="1.0" encoding="UTF-8"?>
<entry>
    <name>jdoe</name>
    <password>1234</password>
    <first>John</first>
    <last>Doe</last>
    <email>jdoe@example.com</email>
    <roles>
        <role>admin</role>
        <role>designer</role>
    </roles>
</entry>

Response¶

Possible HTTP response codes:

Code	Description
201 CREATED	Success
401 UNAUTHORIZED	The username/password used for authentication was invalid.
403 FORBIDDEN	The authenticated user does not have permission to create users on this domain.
409 CONFLICT	The user 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 user.

Example JSON response

{
   "id": "1",
   "name": "user1",
   "first": "Demo",
   "last": "User",
   "email": "user1@example.com",
   "link": [{
      "rel": "self",
      "href": "/liveforms/api/domains/demo/users/user1"
   }]
}

Example XML response

<?xml version="1.0" encoding="UTF-8"?>
<entry>
   <id>1</id>
   <name>user1</name>
   <first>Demo</first>
   <last>User</last>
   <email>user1@example.com</email>
   <link rel="self" href="/liveforms/api/domains/demo/users/user1"/>
</entry>

Update user¶

Description¶

This endpoint accepts information on updating an existing user. The request payload should include a JSON or XML description of the updated user information (see below for examples).

Note

It is possible to rename users with this request. The name of the user 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 user will not be modified by the request.

Request¶

PUT /liveforms/api/domains/{domain}/users/{user}

parameter	description
domain	The name of a domain
user	The name of the user to be updated

Example JSON request

{
   "name": "jdoe",
   "password": "1234",
   "first": "John",
   "last": "Doe",
   "email": "jdoe@example.com",
   "roles": [
      "admin",
      "designer"
   ]
}

Example XML request

<?xml version="1.0" encoding="UTF-8"?>
<entry>
    <name>jdoe</name>
    <password>1234</password>
    <first>John</first>
    <last>Doe</last>
    <email>jdoe@example.com</email>
    <roles>
        <role>admin</role>
        <role>designer</role>
    </roles>
</entry>

Response¶

Possible HTTP response codes:

Code	Description
200 OK	Success
401 UNAUTHORIZED	The username/password used for authentication was invalid.
403 FORBIDDEN	The authenticated user does not have permission to modify users on this domain.
404 NOT FOUND	The user 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 user.

Example JSON response

{
   "id": "1",
   "name": "user1",
   "first": "Demo",
   "last": "User",
   "email": "user1@example.com",
   "link": [{
      "rel": "self",
      "href": "/liveforms/api/domains/demo/users/user1"
   }]
}

Example XML response

<?xml version="1.0" encoding="UTF-8"?>
<entry>
   <id>1</id>
   <name>user1</name>
   <first>Demo</first>
   <last>User</last>
   <email>user1@example.com</email>
   <link rel="self" href="/liveforms/api/domains/demo/users/user1"/>
</entry>

Delete user¶

Description¶

This endpoint accepts requests to delete a user. There is no payload body associated with this request.

Request¶

DELETE /liveforms/api/domains/{domain}/users/{user}

parameter	description
domain	The name of a domain
user	The name of the user to be updated

Response¶

Possible HTTP response codes:

Code	Description
200 OK	Success
401 UNAUTHORIZED	The username/password used for authentication was invalid.
403 FORBIDDEN	The authenticated user does not have permission to delete users on this domain.
404 NOT FOUND	The user 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 user.

Example JSON response

{
   "id": "1",
}

Example XML response

<?xml version="1.0" encoding="UTF-8"?>
<entry>
   <id>1</id>
</entry>