Series

Items in the catalog may be organized into series, expressing an explicit, known ordering of items, if there is any. Typical examples of series may be consecutive TV show episodes, book titles, etc.

Each item may be added to zero or more series, and a series may also be added into another series, resulting in a "meta-series". This may be useful for modeling ordered seasons of a TV show that has the episodes in each season themselves ordered.

Series definition

Methods for managing series - creating, listing, and deleting them.

put

Add Series

Creates a new series in the database.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.AddSeries(seriesId, {
  // optional parameters:
  cascadeCreate: true,  // boolean
}));

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

seriesId

String

Located in: path

Required: Yes

ID of the series to be created.

cascadeCreate

Boolean

Located in: body

Required: No

If set to true, the item will be created with the same ID as the series. Default is true.

Responses

201

Successful operation.

400

The seriesId does not match ^[a-zA-Z0-9_-:@.]+$.

409

Series of the given seriesId is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Delete Series

Deletes the series of the given seriesId from the database.

Deleting a series will only delete assignment of items to it, not the items themselves!

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.DeleteSeries(seriesId, {
  // optional parameters:
  cascadeDelete: false,  // boolean
}));

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

seriesId

String

Located in: path

Required: Yes

ID of the series to be deleted.

cascadeDelete

Boolean

Located in: body

Required: No

If set to true, item with the same ID as seriesId will be also deleted. Default is false.

Responses

200

Successful operation.

400

The seriesId does not match ^[a-zA-Z0-9_-:@.]+$.

404

Series of the given seriesId is not present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the series was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List Series

Gets the list of all the series currently present in the database.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListSeries());

Calls Limit Per Minute

100

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

Responses

200

Successful operation.

[
  "series-1",
  "series-2",
  "series-3"
]

404

Invalid URL.

Series items

Methods for adding items (or even series themselves) to series.

get

List Series Items

Lists all the items present in the given series, sorted according to their time index values.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListSeriesItems(seriesId));

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

seriesId

String

Located in: path

Required: Yes

ID of the series whose items are to be listed.

Responses

200

Successful operation.

[
  {
    "itemType": "item",
    "itemId": "item-x",
    "time": 1
  },
  {
    "itemType": "item",
    "itemId": "item-y",
    "time": 2
  },
  {
    "itemType": "item",
    "itemId": "item-z",
    "time": 3
  }
]

400

The seriesId does not match ^[a-zA-Z0-9_-:@.]+$.

404

Series of the given seriesId is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

post

Insert to Series

Inserts an existing item/series into a series of the given seriesId at a position determined by time.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.InsertToSeries(seriesId, itemType, itemId, time, {
  // optional parameters:
  cascadeCreate: true,  // boolean
}));

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

seriesId

String

Located in: path

Required: Yes

ID of the series to be inserted into.

itemType

String

Located in: body

Required: Yes

item iff the regular item from the catalog is to be inserted, series iff series is inserted as the item.

itemId

String

Located in: body

Required: Yes

ID of the item iff itemType is item. ID of the series iff itemType is series.

time

Number

Located in: body

Required: Yes

Time index used for sorting items in the series. According to time, items are sorted within series in ascending order. In the example of TV show episodes, the episode number is a natural choice to be passed as time.

cascadeCreate

Boolean

Located in: body

Required: No

Indicates that any non-existing entity specified within the request should be created (as if corresponding PUT requests were invoked). This concerns both the seriesId and the itemId. If cascadeCreate is set to true, the behavior also depends on the itemType. In case of item, an item is created, in case of series a series + corresponding item with the same ID is created.

Responses

200

Successful operation.

400

seriesId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or itemType∉{item,series}, or time is not a real number.

404

Series of the given seriesId is not present in the database. Item of the given itemId is not present in the database if itemType is item. Series of the given itemId is not present in the database if itemType is series. If there is no additional info in the JSON response, you probably have an error in your URL.

409

A series item of the exact same (itemType, itemId, time) is already present in the series of seriesId. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Remove from Series

Removes an existing series item from the series.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.RemoveFromSeries(seriesId, itemType, itemId));

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

seriesId

String

Located in: path

Required: Yes

ID of the series from which a series item is to be removed.

itemType

String

Located in: body

Required: Yes

Type of the item to be removed.

itemId

String

Located in: body

Required: Yes

ID of the item iff itemType is item. ID of the series iff itemType is series.

Responses

200

Successful operation.

400

The seriesId or itemId does not match ^[a-zA-Z0-9_-:@.]+$ or itemType∉{item, series}.

404

Series of the given seriesId is not present in the database. Series item given by pair (itemType, itemId) is not present in series of seriesId. If there is no additional info in the JSON response, you probably have an error in your URL.

docs.recombee.com