Users Data and Properties

List All User-Properties

GET users-properties/

Note

Authorized Roles: root, manager, backend

Get all user-properties for the current database.

Response JSON Object
  • properties (list-of-object) –

    All properties

    Inner fields:

    • property_name (string) – [max-length: 64] Property name. Only alphanumeric characters, dots, underscores or hyphens are allowed. The names ‘item_id’ and ‘user_id’ are reserved

    • value_type (string) – [max-length: 10] Property type [see Property Types]

    • repeated (bool) – Whether the property has many values

EXAMPLE RESPONSE
  {
      "properties": [
          {
              "property_name": "age",
              "value_type": "int8",
              "repeated": false
          },
          {
              "property_name": "subscriptions",
              "value_type": "unicode32",
              "repeated": true
          }
      ]
  }

Create New User-Property

POST users-properties/

Note

Authorized Roles: root, manager, backend

Create a new user-property, identified by property_name (case-insensitive).

Request JSON Object
  • property_name (string) – [max-length: 64] Property name. Only alphanumeric characters, dots, underscores or hyphens are allowed. The names ‘item_id’ and ‘user_id’ are reserved

  • value_type (string) – [max-length: 10] Property type [see Property Types]

  • repeated (bool) – Optional. Whether the property has many values

EXAMPLE QUERY BODY
  {
      "property_name": "age",
      "value_type": "int8",
      "repeated": false
  }

Errors:

  • DuplicatedError with error name DUPLICATED_USER_PROPERTY if a user property with the same name already exists

  • WrongData with error name WRONG_DATA_TYPE if value_type is invalid

Get One User-Property

GET users-properties/<str:property_name>/

Note

Authorized Roles: root, manager, backend

Get one user-property given its property_name.

Response JSON Object
  • property_name (string) – [max-length: 64] Property name. Only alphanumeric characters, dots, underscores or hyphens are allowed. The names ‘item_id’ and ‘user_id’ are reserved

  • value_type (string) – [max-length: 10] Property type [see Property Types]

  • repeated (bool) – Optional. Whether the property has many values

EXAMPLE RESPONSE
  {
      "property_name": "age",
      "value_type": "int8",
      "repeated": false
  }

Errors:

  • NotFoundError with error name USER_PROPERTY_NOT_FOUND if the property name cannot be found

Delete User-Property

DELETE users-properties/<str:property_name>/

Note

Authorized Roles: root, manager, backend

Delete an user-property given by its name

Errors:

  • NotFoundError with error name USER_PROPERTY_NOT_FOUND if the property name cannot be found

Get Properties of One User

GET users/<str:user_id>/

Note

Authorized Roles: root, manager, backend

Get one user given its ID.

Response JSON Object
  • user (object) – User data

EXAMPLE RESPONSE
  {
      "user": {
          "user_id": "123e4567-e89b-12d3-a456-426614174000",
          "subscriptions": ["channel1", "channel2"],
          "age": 25
      }
  }

Errors:

  • NotFoundError with error name USER_NOT_FOUND if no user with the given user_id can be found

Create or Update One User

PUT users/<str:user_id>/

Note

Authorized Roles: root, manager, backend

Create a new user, or update it if the user_id already exists.

All properties need to be defined beforehand, see Items and Users Properties.

Note that user_id cannot be a “null” or “falsy” value, such as empty string or 0.

Request JSON Object
  • user (object) – User data

Example:

EXAMPLE QUERY BODY
  {
      "user": {
          "subscriptions": ["channel1", "channel2"],
          "age": 25
      }
  }

Errors:

  • WrongData with error name WRONG_DATA_TYPE if the properties are invalid

Partial Update One User

PATCH users/<str:user_id>/

Note

Authorized Roles: root, manager, backend

Partially update some properties of an user. The properties that are not listed in the request body will be left unchanged. The list of values given for repeated properties will replace (not append) the previous list of values.

Use the body parameter create_if_missing to control whether an error should be returned or a new user should be created when the user_id does not already exist.

All properties need to be defined beforehand, see Items and Users Properties.

Note that user_id cannot be a “null” or “falsy” value, such as empty string or 0.

Request JSON Object
  • user (object) – User data

  • create_if_missing (bool) – Optional. Create user that does not exist

Example:

EXAMPLE QUERY BODY
  {
      "user": {
          "subscriptions": ["channel1", "channel2"],
          "age": 25
      },
      "create_if_missing": false
  }

Errors:

  • WrongData with error name WRONG_DATA_TYPE if the properties are invalid

  • NotFoundError only when create_if_missing=False with error name USER_NOT_FOUND if no user with the given user_id can be found

Create or Update Many Users In Bulk

PUT users-bulk/

Note

Authorized Roles: root, manager, backend

Create many users in bulk, or update the ones for which the user_id already exist.

All properties need to be defined beforehand, see Items and Users Properties.

Note that user_id cannot be a “null” or “falsy” value, such as empty string or 0.

Request JSON Object
  • users (object-array) –

    (additional fields may be present) Users values

    Inner fields:

  • users_m2m (list-of-object) –

    Optional. Users repeated values in array-optimized many-to-many format for binary clients [see Repeated Values]

    Inner fields:

    • name (string) – [max-length: 64] M2M name

    • array (object-array) – M2M array

      Inner fields:

      • user_index (uint32) – User index (0-based)

      • value_id (any) – M2M related object ID

  • wait_for_completion (bool) – Optional. Default is true to wait for completion and respond with 200 OK. Set to false to respond immediately with 202 Accepted after validation, and process asynchronously in the background. The background process may take 30 seconds to start, and there is no way to get notified when the process is complete. No validation of users properties values is done beforehand, the background task may fail silently.

EXAMPLE QUERY BODY (JSON client)
  {
      "users": [
          {
              "user_id": "123e4567-e89b-12d3-a456-426614174000",
              "age": 25,
              "subscriptions": ["channel1", "channel2"]
          },
          {
              "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "age": 32,
              "subscriptions": ["channel1"]
          }
      ]
  }
EXAMPLE QUERY BODY (array-optimized format for binary client)
  {
      "users": [
          {
              "user_id": "123e4567-e89b-12d3-a456-426614174000",
              "age": 25
          },
          {
              "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "age": 32
          }
      ],
      "users_m2m": [
          {
              "name": "subscriptions",
              "array": [
                  {"user_index": 0, "value_id": "channel1"},
                  {"user_index": 0, "value_id": "channel2"},
                  {"user_index": 1, "value_id": "channel1"}
              ]
          }
      ]
  }

Note that we represent the arrow-optimized using JSON for reability, but you should use a binary array instead

Errors:

  • WrongData with error name WRONG_DATA_TYPE if the properties are invalid

  • DuplicatedError with error name DUPLICATED_USER_ID if a user_id occurs multiple times in the same request

List Properties of All Users in Bulk

GET users-bulk/

Note

Authorized Roles: root, manager, backend

Get multiple users by page. The response is paginated, you can control the response amount and offset using the query parameters amt and cursor.

Note that the array-optimized format users_m2m for repeated values is used only for binary clients. Otherwise (e.g. JSON client), the repeated values are formatted as lists in each individual users.

Query Parameters
  • amt (int) – Optional. [max: 500] Maximum amount of users returned, by default is 300

  • cursor (string) – Optional. Pagination cursor, typically from the next_cursor value from the previous response

EXAMPLE QUERY PARAMS
  ?amt=100&cursor=Q21vU1pHb1FjSEp...
Response JSON Object
  • users (object-array) –

    (additional fields may be present) Users values

    Inner fields:

  • users_m2m (list-of-object) –

    Users repeated values in array-optimized many-to-many format for binary clients [see Repeated Values]

    Inner fields:

    • name (string) – [max-length: 64] M2M name

    • array (object-array) – M2M array

      Inner fields:

      • user_index (uint32) – User index (0-based)

      • value_id (any) – M2M related object ID

  • has_next (bool) – Indicates whether or not there are more users to request

  • next_cursor (string) – Pagination cursor to use in next request to get more users

EXAMPLE RESPONSE (JSON client)
  {
      "users": [
          {
              "user_id": "123e4567-e89b-12d3-a456-426614174000",
              "age": 25,
              "subscriptions": ["channel1", "channel2"]
          },
          {
              "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "age": 32,
              "subscriptions": ["channel1"]
          }
      ],
      "has_next": true,
      "next_cursor": "Q21vU1pHb1FjSEp..."
  }

Partial Update Many Users In Bulk

PATCH users-bulk/

Note

Authorized Roles: root, manager, backend

Partially update some properties of many users. The properties that are not listed in the request body will be left unchanged. The list of values given for repeated properties will replace (not append) the previous list of values.

Use the body parameter create_if_missing to control whether an error should be returned or new users should be created when the user_id does not already exist.

All properties need to be defined beforehand, see Items and Users Properties.

Note that user_id cannot be a “null” or “falsy” value, such as empty string or 0.

Request JSON Object
  • users (object-array) –

    (additional fields may be present) Users values

    Inner fields:

  • users_m2m (list-of-object) –

    Optional. Users repeated values in array-optimized many-to-many format for binary clients [see Repeated Values]

    Inner fields:

    • name (string) – [max-length: 64] M2M name

    • array (object-array) – M2M array

      Inner fields:

      • user_index (uint32) – User index (0-based)

      • value_id (any) – M2M related object ID

  • wait_for_completion (bool) – Optional. Default is true to wait for completion and respond with 200 OK. Set to false to respond immediately with 202 Accepted after validation, and process asynchronously in the background. The background process may take 30 seconds to start, and there is no way to get notified when the process is complete. No validation of users properties values is done beforehand, the background task may fail silently.

  • create_if_missing (bool) – Optional. Create users that do not exist

EXAMPLE QUERY BODY (JSON client)
  {
      "users": [
          {
              "user_id": "123e4567-e89b-12d3-a456-426614174000",
              "age": 25,
              "subscriptions": ["channel1", "channel2"]
          },
          {
              "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "age": 32,
              "subscriptions": ["channel1"]
          }
      ],
      "create_if_missing": false
  }

Errors:

  • WrongData with error name WRONG_DATA_TYPE if the properties are invalid

  • DuplicatedError with error name DUPLICATED_USER_ID if a user_id occurs multiple times in the same request

  • NotFoundError only when create_if_missing=False with error name USER_NOT_FOUND if at least one user with the given user_id cannot be found

List Properties of Many Users by ID

POST users-bulk/list/

Note

Authorized Roles: root, manager, backend

Get multiple users given their IDs. Note that the HTTP verb is POST so that users ids can be sent in the body, but the endpoint is stateless as GET.

The users in the response are not aligned with the input. In particular this endpoint does not respond with 404 if any user in missing. Instead, the missing users are simply not present in the response.

Note that the array-optimized format users_m2m for repeated values is used only for binary clients. Otherwise (e.g. JSON client), the repeated values are formatted as lists in each individual users.

Request JSON Object
  • users_id (ID-array) – Users IDs

EXAMPLE QUERY BODY
  {
      "users_id": [
          "123e4567-e89b-12d3-a456-426614174000",
          "c3391d83-553b-40e7-818e-fcf658ec397d"
      ]
  }
Response JSON Object
  • users (object-array) –

    (additional fields may be present) Users values

    Inner fields:

  • users_m2m (list-of-object) –

    Users repeated values in array-optimized many-to-many format for binary clients [see Repeated Values]

    Inner fields:

    • name (string) – [max-length: 64] M2M name

    • array (object-array) – M2M array

      Inner fields:

      • user_index (uint32) – User index (0-based)

      • value_id (any) – M2M related object ID

EXAMPLE RESPONSE (JSON client)
  {
      "users": [
          {
              "user_id": "123e4567-e89b-12d3-a456-426614174000",
              "age": 25,
              "subscriptions": ["channel1", "channel2"]
          },
          {
              "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "age": 32,
              "subscriptions": ["channel1"]
          }
      ]
  }