Description

The ListUsers API allows the Account Owner to retrieve a list of all the Users that were previously created, along with any requested attributes. The list of Users can be restricted by passing a query condition.

What is a User?

With Apstrata, you can build multi-user applications. In order to be able to read or write data to an apstrata account store, you have to be the Account Owner or you have to be registered as a User in the apstrata account. API requests signed with a User password are User requests as opposed to owner requests which are signed with the account secret.

When you register with Apstrata, an account will be created for you. With each account creation, there is a default user Schema named "apsdb_user" that gets created. The purpose of this Schema is to give the owner the possibility of defining custom user profiles. Hence, an owner can add new fields, define permissions, and define validation rules for each field. When saving users, custom user attributes can be set and validated automatically based on the rules defined for each one. The fields already defined in the default user Schema are required and should not be removed. This user schema is not meant to be used for saving non-user documents.

A User entity is persisted as a Document in the apstrata account user directory Store, based on the Schema named "apsdb_user".

A User can belong to zero or more Groups defining his read and write permissions.

A user can be suspended by calling SaveUser and setting the system field "isSuspended" to true. A suspended user still exists in the system but is treated as if he was deleted. Any request made to Apstrata with this user will return an exception saying that the signature is invalid. The user can be reactivated by calling SaveUser and setting the field "isSuspended" back to false. By default, the ACL of this field are set in a way that only the owner of the account can suspend or un-suspend a user but you are free to change those ACLs by updating your user schema.

Note that owners will always have the permission to call the GetUser and SaveUser APIs, but Users can only read or update their own profile Documents. In other words, the permissions defined in the Schema ACLs can only be used to restrict Users from accessing their own profile Document or other Users profile Documents.

For more details about schema definition, please refer to Document Schema Definition.

Specific Request Parameters

(Refer to Common Request Parameters)

Name	Description	Required	Default	Possible Values
apsdb.attributes	A comma separated list of attributes that will be returned for each user in the list. The %%*%% is supported for returning all the attributes. The users will be returned without attributes if this parameter is not sent or sent as empty.	No
apsdb.query	The query condition used to list the users. The query condition syntax is the same query condition syntax used for the query service.	No		Refer to the query condition syntax under the Query section.
apsdb.ftsQuery	This string is used to refine the search after executing the query condition by performing a full text search on the returned documents.	No
apsdb.count	Specifies if the amount of results should be returned or not. When set to true, the total number of documents found by the search will be returned. However, if the apsdb.ftsQuery parameter was sent in the request, the count will be equal to the number of documents returned in the first page instead of the total number of hits.	No	false	true/false
apsdb.resultsPerPage	Determines the number of results per page to return.	No	"Max documents in query response" defined in the accounts limits section.	Integer less or equal to the "Max documents in query response" defined in the account limits section.
apsdb.pageNumber	Determines which page should be returned, in case there are more than one.	No	1	Integer greater than 1.
apsdb.sort	The attributes on which to sort.	No		Refer to the sort syntax under the Query section.
apsdb.includeFieldType	To limit response size, the returned JSON responses do not include field type information for each field in a user document. Setting this paramter to true will cause each user document to have an additional attribute in the JSON response, named "_type", which lists the fields included in the user document and their corresponding field types.	No	false	true false

Specific Response Elements

(Refer to Common Response Elements)

The following specific "result" element is a child of the common root element "response" and a sibling of the common "metadata" element:

{
	"result": {
		"users": [
			{
				"login": ["login name of a user"], 
				"name": ["full name of a user"], 
				"email": ["email address of a user"], 
				"groups": ["name of a group for a user", "name of another group for a user"], 
				"customField": ["value of custom field for a user"]
			},
			{
				"login": ["login name of another user"], 
				"name": ["full name of another user"], 
				"email": ["email address of another user"], 
				"groups": ["name of a group for another user", "name of another group for another user"], 
				"customField": ["value of custom field for another user"]
			},
		]
	}
}

Specific Logical Errors

(Refer to Common Logical Error Codes)

Error	Message	Status Code
INVALID_QUERY_CONDITION	There is an error in the syntax of your query, refer to the user documentation for help.	400
INVALID_ATTRIBUTES_SYNTAX	You can send either a comma separated list of field names or the symbol * in the parameter 'apsdb.attributes' but not both.	400
INVALID_QUERY_REQUEST		400
INCORRECT_DATE_FORMAT		400
SERVICE_EXECUTION_TIME_EXCEEDED		409
MAX_PREDICATES_EXCEEDED		400
PERMISSION_DENIED	You don't have enough permissions to execute this query.	403
MAX_RESPONSE_DOCUMENTS_EXCEEDED	The number of results [resultsPerPage] is larger than the maximum allowed number of results [maxResults].	400
STRING_TO_NUMERIC_EXCEPTION	Cannot convert string value to int. Evaluated value [ResultsPerPage].	400

Examples

Sample Request

Request URL: http://sandbox.apstrata.com/apsdb/rest/[authenticationkey]/ListUsers?apsws.time=[timestamp]&apsws.authSig=[signature]

POST parameters:

apsdb.attributes=login,age
apsdb.count=true
apsdb.pageNumber=1
apsdb.query=age<numeric>21
apsdb.resultsPerPage=3
apsdb.sort=login<string:ASC>

Sample XML Response

Success XML:

<response>
    <metadata>
        <requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
        <status>success</status>
        <statusCode>200</statusCode>
    </metadata>
    <result>
        <count>5</count>
        <users>
            <user>
                <attributes>
                    <attribute name="login">
                        <values>
                            <value>Alice</value>
                        </values>
                    </attribute>
                    <attribute name="age">
                        <values>
                            <value>22.0</value>
                        </values>
                    </attribute>
                </attributes>
            </user>
            <user>
                <attributes>
                    <attribute name="login">
                        <values>
                            <value>Bob</value>
                        </values>
                    </attribute>
                    <attribute name="age">
                        <values>
                            <value>32.0</value>
                        </values>
                    </attribute>
                </attributes>
            </user>
            <user>
                <attributes>
                    <attribute name="login">
                        <values>
                            <value>John</value>
                        </values>
                    </attribute>
                    <attribute name="age">
                        <values>
                            <value>25.0</value>
                        </values>
                    </attribute>
                </attributes>
            </user>
        </users>
    </result>
</response>

Failure XML:

<response>
    <metadata>
        <requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
        <status>failure</status>
        <errorCode>[errorCode]</errorCode>
        <errorDetail>[errorDetail]</errorDetail>
        <statusCode>[statusCode]</statusCode>
    </metadata>
</response>

Sample JSON Response

{"response": {
  "metadata": {
    "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "success",
    "statusCode": "200"
  },
  "result": {
    "count": "5",
    "users": [
      {
        "login": [
          "Alice"
        ],
        "age": [
          "22.0"
        ]
      },
      {
        "login": [
          "Bob"
        ],
        "age": [
          "32.0"
        ]
      },
      {
        "login": [
          "John"
        ],
        "age": [
          "25.0"
        ]
      }
    ]
  }
}}

Child pages

ListUsers

Description

Specific Request Parameters

Specific Response Elements

Specific Logical Errors

Examples