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
, andsearchRequest
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
, andsearchRequest
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.