Update a swift collection - Fluid Topics - Latest

Fluid Topics API Reference Guide

Category
Reference Guides
Audience
public
Version
Latest

This web service updates a swift collection that was previously added to the user's library.

Method Endpoint
PUT /api/users/{userId}/collections/{collectionId}
Path parameter Type Description
{userId} String The user's identifier.
{collectionId} String The identifier of the collection as retrieved when listing collections.
  • The title, description, color, and searchRequest parameters are optional, but it is necessary to specify at least one.
  • Only parameters included in the query are updated. Parameters not included in the query remain unchanged.

Request example

The following lines show an example of a JSON request body:

{
  "title": "My updated swift collection",
  "description": "An updated swift collection of topics about xyz",
  "color": "green",
  "searchRequest": {
    "contentLocale": "en-US",
    "query": "xyz", 
    "filters": [
      {
        "key": "ft:editorialType",
        "values": ["book"],
        "negative": false
      }
    ],
    "sort": [
      {
        "type": "NATURAL",
        "key": "afs:sort=versionFacet",
        "order": "DESC"
      }
    ],
    "periodFilter": {
      "periodType": "CUSTOM",
      "period": {
        "from": "2022-07-08",
        "to": "2022-10-13"
      }
    }
  }
}
Field Type Required? Description
title String No A name for the swift collection.
description String No A description of the swift collection.
color String No A color for the swift collection's tag. Accepted values are black, green, blue, purple, red, orange, and yellow.
searchRequest Object No The parameters of the search corresponding to the swift collection.
    contentLocale String Yes Indicates the language of the search results.
    query String No The keywords of the query.
    filters Array No An array of filters applied to the query.
        key String Yes A metadata key for the filter.
        values Array Yes A list of metadata values for the filter's metadata key.
    sort Array No An optional element of the searchRequest parameter defining whether search results should be sorted based on certain criteria.
            key String No A parameter prefixed by afs:sort that defines additional criteria by which to sort search results.
            order String No Defines the sort order. Possible values are ASC and DESC.
            type String Yes The sorting method to be applied to search results. Possible values are ALPHA and NATURAL.
    periodFilter Object No An optional element of the searchRequest parameter that filters search results by period.
        periodType String Yes Defines the type of period by which to filter the search results. Possible values include LAST_WEEK, LAST_MONTH, LAST_YEAR and CUSTOM.
        period Object No Defines the start and end of the period by which to filter the search results.
            from String Yes The start date of the period by which to filter the search results.
            to String Yes The end date of the period by which to filter the search results.
Return code Description
20O OK The collection was updated.
400 BAD REQUEST A required parameter is missing or an invalid color was provided for the collection's tag.
401 UNAUTHORIZED The authorization header is absent or invalid.
403 FORBIDDEN The user or API key does not have the USERS_ADMIN or ADMIN role, or the user corresponding to the USER_ID parameter does not have the COLLECTION_USER role.
404 NOT FOUND No user exists with this ID, the identifier for the documents parameter does not correspond to an existing document or no collection matches the COLLECTION_ID.
  • The title, description, color, and searchRequest parameters are optional, but it is necessary to specify at least one.
  • Only fields included in the request body are updated. Fields not included in the request body remain the same.

Response body

{
  "ownerId": "d433cb2q-8d2f-4aaf-a8fc-917e154b4ceb",
  "id": "bf93cb2q-3070-4aaf-a134-917e154b4ceef",
  "title": "My updated swift collection",
  "description": "An updated swift collection of topics about xyz",
  "color": "green",
  "searchRequest": {
    "contentLocale": "en-US",
    "query": "xyz", 
    "filters?": [
      {
        "key": "ft:editorialType",
        "values": "book",
        "negative": false
      }
    ],
    "sort": [
      {
        "type": "NATURAL",
        "key": "afs:sort=versionFacet",
        "order": "DESC"
      }
    ],
    "periodFilter": {
      "periodType": "CUSTOM",
      "period": {
        "from": "2022-07-08",
        "to": "2023-10-13"
      }
    }
  },
  "documentsUrl": "https://fluid-topics/api/users/{userId}/collections/{collectionId}/documents",
  "creationDate": "2023-10-22T15:10:07.126+00:00",
  "lastUpdate": "2023-10-22T15:10:07.126+00:00",
}
Field Type Description
ownerId String The identifier of the user who owns the collection.
id String The identifier of the collection.
title String The name of the collection.
description String The description of the collection.
color String The color of the collection's tag.
searchRequest Object The parameters of the search corresponding to the swift collection.
    contentLocale String Indicates the language of the search results.
    query String The keywords of the query.
    filters Array An array of filters applied to the query.
key String A metadata key for the filter.
values Array A list of values for the metadata key.
    sort Array An optional element of the searchRequest parameter defining whether search results should be sorted based on certain criteria.
key String An element prefixed by afs:sort that defines additional criteria by which to sort search results.
order String An element that defines the sort order. Possible values are ASC and DESC.
type String The sorting method to be applied to search results. Possible values are ALPHA and NATURAL.
    periodFilter Object An optional element of the searchRequest parameter that filters search results by period.
periodType String Defines the type of period by which to filter the search results. Possible values include LAST_WEEK, LAST_MONTH, LAST_YEAR and CUSTOM.
period Object Defines the start and end of the period by which to filter the search results.
from String The start date of the period by which to filter the search results.
to String The end date of the period by which to filter the search results.
documentsUrl String A URL to retrieve the list of documents in the collection.
creationDate String The date and time when the collection was created.
lastUpdate String The date and time when the collection was last updated.

If the request body does not include the searchRequest parameter, neither will the output.