This document describes the favorites resource.
A favorite is something that a user has decided is important enough that it should be more readily accessible than other resources of the same time.
Resources¶
Favorite¶
A favorite is modeled as a UUID having the same value has the important resource's UUID.
Example
f86700ac-df88-11e3-bf3b-6abdce5a08d1
Data Id Collection¶
A collection of data Ids is its own resource. It is a JSON document (media type application/json
) with a single filesystem
field that holds an array of UUIDs, each for a file or folder.
Example
{
"filesystem" : [
"f86700ac-df88-11e3-bf3b-6abdce5a08d1",
"9cdb9492-f288-11e3-ab3e-13be1320bb50"
]
}
Favorite Data Collection¶
A collection of favorite data or filesystem entities is its own resource. It is a JSON document (media type application/json
) with the following fields.
Field | Type | Description |
---|---|---|
files | array | an array of favorite file objects |
folders | array | an array of favorite folder objects |
total | number | the total number of favorite files and folders for a given authenticated user |
Favorite File Object¶
A favorite file object has the following fields.
Field | Type | Description |
---|---|---|
date-created | number | the time when the file was created in ms since the POSIX epoch |
date-modified | number | the time when the file was last modified in ms since the POSIX epoch |
file-size | number | the size in bytes of the file |
id | string | the absolute path to the file |
infoType | string | the semantic type of the content of the file |
isFavorite | boolean | true |
label | string | the name of file relative to its containing folder |
mime-type | string | the media type of the file |
path | string | the absolute path to the file |
permission | string | the permission the authenticated user has on the file, "read"|"write"|"own" |
share-count | number | the number of other users this file has been shared with |
type | string | "file" |
uuid | string | the file's UUID |
Favorite Folder Object¶
A favorite folder object has the following fields.
Field | Type | Description |
---|---|---|
date-created | number | the time when the folder was created in ms since the POSIX epoch |
date-modified | number | the time when the folder was last modified (i.e. had a member file or folder added or removed) in ms since the POSIX epoch |
dir-count | number | the number of member folders |
file-count | number | the number of member files |
file-size | number | 0 |
id | string | the absolute path to the folder |
isFavorite | boolean | true |
label | string | the name of folder relative to its containing folder |
path | string | the absolute path to the folder |
permission | string | the permission the authenticated user has on the folder, "read"|"write"|"own" |
share-count | number | the number of other users this folder has been shared with |
type | string | "dir" |
uuid | string | the folder's UUID |
Endpoints¶
Marking a Data Resource as Favorite¶
PUT /secured/favorites/filesystem/{favorite}
Delegates to metadata: PUT /favorites/filesystem/{favorite}
This endpoint marks a given file or folder a favorite of the authenticated user. {favorite}
is the UUID of the file or folder being marked.
This endpoint forwards requests to the corresponding metadata service endpoint. Please see the metadata documentation for more information.
Request¶
A request to this endpoint requires no parameters. The user that owns the favorite is determined from the authentication. Any query parameters will be ignored.
Any body attached to the request will be ignored.
Response¶
Status Code | Cause |
---|---|
200 | The file or folder corresponding to the <favorite> UUID has been marked as a favorite of the authenticated user. |
401 | Either the authentication header was not provided, or its value wasn't correct. |
404 | The {favorite} UUID doesn't belong to a known file or folder or the file or folder isn't readable by the authenticated user. |
Error responses may contain a "reason"
field, providing a short, human readable explanation of the failure.
Example¶
? curl -XPUT -H "$AUTH_HEADER" localhost/secured/favorites/filesystem/f86700ac-df88-11e3-bf3b-6abdce5a08d1
Removing a Data Resource from Being a Favorite¶
DELETE /secured/favorites/filesystem/{favorite}
Delegates to metadata: DELETE /favorites/filesystem/{favorite}
This endpoint removes a given file or folder from the authenticated user's favorites. <favorite>
is the UUID of the file or folder.
This endpoint forwards requests to the corresponding metadata service endpoint. Please see the metadata documentation for more information.
Request¶
A request to this endpoint requires no parameters. The user that owns the favorite is determined from the authentication. Any query parameters will be ignored.
Any body attached to the request will be ignored.
Response¶
Status Code | Cause |
---|---|
200 | The file or folder corresponding to the favorite UUID has been marked as a favorite of the authenticated user. |
401 | Either the authentication header was not provided, or its value wasn't correct. |
404 | The file or folder corresponding to the favorite UUID wasn't marked as a favorite. |
Error responses may include a reason
field, providing a short, human readable explanation of the failure.
Example¶
? curl -H "$AUTH_HEADER" -XDELETE localhost/secured/favorites/filesystem/f86700ac-df88-11e3-bf3b-6abdce5a08d1
Listing Stat Info for Favorite Data¶
GET /secured/favorites/filesystem
Requires metadata endpoint: GET /favorites/filesystem
This endpoint lists stat information for the authenticated user's favorite files and folders. Only files and folders accessible to the user will be listed. The result set is paged.
This endpoint fetches favorite information from the corresponding metadata service endpoint before applying filters, sorting, and additional stat information. Please see the metadata documentation for more information.
Request¶
A request to this endpoint requires the parameters in the following table.
Parameter | Required? | Default | Description |
---|---|---|---|
sort-col | yes | the field used to sort the filesystem entries in the result set. This can be NAME|ID|LASTMODIFIED|DATECREATED|SIZE . All values are case insensitive. |
|
sort-dir | yes | the sorting direction. It can be ASC|DESC . Both values are case insensitive. |
|
limit | yes | the maximum number of filesystem entries to return | |
offset | yes | the number entries in the sorted total result set to skip before including entries in the response document. | |
entity-type | no | ANY | the type of entities to return. It can be ANY|FILE|FOLDER . All values are case-insensitive. |
info-type | no | no filtering | filter the files portion of the result set so that only files with this info type are returned. To return multiple info types, and this parameter more than once. |
Any additional parameters will be ignored.
Any body attached to the request will be ignored.
Response¶
Status Code | Cause |
---|---|
200 | The list of stat info was obtained and is included in the response body. |
400 | one of the parameters was missing or had a nonsensical value. |
401 | Either the authentication header was not provided, or its value wasn't correct. |
Upon success, the response body will be a data collection JSON document containing the stat information of the favorite files and folders.
Error responses may include a reason
field, providing a short, human readable explanation of the failure.
Example¶
? curl -H "$AUTH_HEADER" "localhost/secured/favorites/filesystem/favorites?sort-col=ID&sort-dir=ASC&limit=1&offset=0"
{
"filesystem": {
"files": [],
"folders": [
{
"date-created": 1.397233899e+12,
"date-modified": 1.397233899e+12,
"dir-count": 256,
"file-count": 0,
"id": "/iplant/home/wregglej/analyses",
"isFavorite": true,
"label": "analyses",
"path": "/iplant/home/wregglej/analyses",
"permission": "own",
"share-count": 1,
"type": "dir",
"uuid": "0d880c78-df8a-11e3-bfa5-6abdce5a08d5"
}
],
"total": 3
}
}
Filter a Set of Resources for Favorites¶
POST /secured/favorites/filter
Delegates to metadata: POST /favorites/filter
This endpoint forwards requests to the corresponding metadata service endpoint. Please see the metadata documentation for more information.
This endpoint fetches the filtered favorite IDs from the corresponding metadata service endpoint before further filtering only UUIDs for files and folders accessible to the user.
Request¶
A request to this endpoint requires no parameters. The user that owns the favorite is determined from the authentication. Any query parameters will be ignored.
Response¶
Status Code | Cause |
---|---|
200 | The filtered list of UUIDs was generated and is included in the response body. |
400 | The request body wasn't a syntactically correct data id collection. |
401 | Either the authentication header was not provided, or its value wasn't correct. |
Upon success, the response body will be a data id collection JSON document containing the UUIDs from the request body that correspond to favorite files and folders of the user.
Error responses may include a reason
field, providing a short, human readable explanation of the failure.
Example¶
? curl -XPOST -H "$AUTH_HEADER" -d '
{
"filesystem" : [
"f86700ac-df88-11e3-bf3b-6abdce5a08d1",
"f86700ac-df88-11e3-bf3b-6abdce5a08d5"
]
}' localhost/secured/favorites/filter
{
"filesystem" : [
"f86700ac-df88-11e3-bf3b-6abdce5a08d1"
]
}