Items Data and Properties

List All Item-Properties

GET items-properties/

Note

Authorized Roles: root, manager, backend

Get all item-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": "price",
              "value_type": "float32",
              "repeated": false
          },
          {
              "property_name": "tags",
              "value_type": "unicode32",
              "repeated": true
          },
          {
              "property_name": "genres",
              "value_type": "unicode16",
              "repeated": true
          }
      ]
  }

Create New Item-Property

POST items-properties/

Note

Authorized Roles: root, manager, backend

Create a new item-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": "price",
      "value_type": "float32",
      "repeated": false
  }

Errors:

  • DuplicatedError with error name DUPLICATED_ITEM_PROPERTY if an item property with the same name already exists

  • WrongData with error name WRONG_DATA_TYPE if value_type is invalid

Get One Item-Property

GET items-properties/<str:property_name>/

Note

Authorized Roles: root, manager, backend

Get one item-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": "price",
      "value_type": "float32",
      "repeated": false
  }

Errors:

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

Delete Item-Property

DELETE items-properties/<str:property_name>/

Note

Authorized Roles: root, manager, backend

Delete an item-property given by its name

Errors:

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

Get Properties of One Item

GET items/<str:item_id>/

Note

Authorized Roles: root, manager, backend

Get one item properties given its ID.

Response JSON Object
  • item (object) – Item data

EXAMPLE RESPONSE
  {
      "item": {
          "item_id": "123e4567-e89b-12d3-a456-426614174000",
          "tags": ["family", "sci-fi"],
          "genres": ["drama", "comedy"],
          "price": 9.99
      }
  }

Errors:

  • NotFoundError with error name ITEM_NOT_FOUND if no item with the given item_id can be found

Create or Replace One Item

PUT items/<str:item_id>/

Note

Authorized Roles: root, manager, backend

Create a new item, or replace it if the item_id already exists.

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

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

Request JSON Object
  • item (object) – Item data

EXAMPLE QUERY BODY
  {
      "item": {
          "tags": ["family", "sci-fi"],
          "genres": ["drama", "comedy"],
          "price": 9.99
      }
  }

Errors:

  • WrongData with error name WRONG_DATA_TYPE if the properties are invalid

Partial Update One Item

PATCH items/<str:item_id>/

Note

Authorized Roles: root, manager, backend

Partially update some properties of an item. 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 item should be created when the item_id does not already exist.

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

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

Request JSON Object
  • item (object) – Item data

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

EXAMPLE QUERY BODY
  {
      "item": {
          "tags": ["family", "sci-fi"],
          "genres": ["drama", "comedy"],
          "price": 9.99
      },
      "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 ITEM_NOT_FOUND if no item with the given item_id can be found

Create or Replace Many Items in Bulk

PUT items-bulk/

Note

Authorized Roles: root, manager, backend

Create many items in bulk, or replace the ones for which the item_id already exist.

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

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

Request JSON Object
  • items (object-array) –

    (additional fields may be present) Items values

    Inner fields:

  • items_m2m (list-of-object) –

    Optional. Items 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:

      • item_index (uint32) – Item 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 items properties values is done beforehand, the background task may fail silently.

EXAMPLE QUERY BODY (JSON client)
  {
      "items": [
          {
              "item_id": "123e4567-e89b-12d3-a456-426614174000",
              "price": 9.99,
              "tags": ["family", "sci-fi"],
              "genres": ["drama", "comedy"]
          },
          {
              "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "price": 4.49,
              "tags": ["family"],
              "genres": ["thriller"]
          }
      ]
  }
EXAMPLE QUERY BODY (array-optimized format for binary client)
  {
      "items": [
          {
              "item_id": "123e4567-e89b-12d3-a456-426614174000",
              "price": 9.99
          },
          {
              "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "price": 4.49
          }
      ],
      "items_m2m": [
          {
              "name": "tags",
              "array": [
                  {"item_index": 0, "value_id": "family"},
                  {"item_index": 0, "value_id": "sci-fi"},
                  {"item_index": 1, "value_id": "family"}
              ]
          },
          {
              "name": "genres",
              "array": [
                  {"item_index": 0, "value_id": "drama"},
                  {"item_index": 0, "value_id": "comedy"},
                  {"item_index": 1, "value_id": "thriller"}
              ]
          }
      ]
  }

Note that we represent the array-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_ITEM_ID if an item_id occurs multiple times in the same request

List Properties of All Items in Bulk

GET items-bulk/

Note

Authorized Roles: root, manager, backend

Get multiple items 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 items_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 items.

Query Parameters
  • amt (int) – Optional. [max: 500] Maximum amount of items 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
  • items (object-array) –

    (additional fields may be present) Items values

    Inner fields:

  • items_m2m (list-of-object) –

    Items 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:

      • item_index (uint32) – Item index (0-based)

      • value_id (any) – M2M related object ID

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

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

EXAMPLE RESPONSE (JSON client)
  {
      "items": [
          {
              "item_id": "123e4567-e89b-12d3-a456-426614174000",
              "price": 9.99,
              "tags": ["family", "sci-fi"],
              "genres": ["drama", "comedy"]
          },
          {
              "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "price": 4.49,
              "tags": ["family"],
              "genres": ["thriller"]
          }
      ],
      "has_next": true,
      "next_cursor": "Q21vU1pHb1FjSEp..."
  }

Partial Update Many Items in Bulk

PATCH items-bulk/

Note

Authorized Roles: root, manager, backend

Partially update some properties of many items. 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 items should be created when the item_id does not already exist.

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

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

Request JSON Object
  • items (object-array) –

    (additional fields may be present) Items values

    Inner fields:

  • items_m2m (list-of-object) –

    Optional. Items 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:

      • item_index (uint32) – Item 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 items properties values is done beforehand, the background task may fail silently.

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

EXAMPLE QUERY BODY (JSON client)
  {
      "items": [
          {
              "item_id": "123e4567-e89b-12d3-a456-426614174000",
              "price": 9.99,
              "tags": ["family", "sci-fi"],
              "genres": ["drama", "comedy"]
          },
          {
              "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "price": 4.49,
              "tags": ["family"],
              "genres": ["thriller"]
          }
      ],
      "create_if_missing": false
  }

Errors:

  • WrongData with error name WRONG_DATA_TYPE if the properties are invalid

  • DuplicatedError with error name DUPLICATED_ITEM_ID if an item_id occurs multiple times in the same request

  • NotFoundError only when create_if_missing=False with error name ITEM_NOT_FOUND if at least one item with the given item_id cannot be found

List Properties of Many Items by ID

POST items-bulk/list/

Note

Authorized Roles: root, manager, backend

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

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

Note that the array-optimized format items_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 items.

Request JSON Object
  • items_id (ID-array) – Items IDs

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

    (additional fields may be present) Items values

    Inner fields:

  • items_m2m (list-of-object) –

    Items 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:

      • item_index (uint32) – Item index (0-based)

      • value_id (any) – M2M related object ID

EXAMPLE RESPONSE (JSON client)
  {
      "items": [
          {
              "item_id": "123e4567-e89b-12d3-a456-426614174000",
              "price": 9.99,
              "tags": ["family", "sci-fi"],
              "genres": ["drama", "comedy"]
          },
          {
              "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "price": 4.49,
              "tags": ["family"],
              "genres": ["thriller"]
          }
      ]
  }