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.

Favorite File Object

A favorite file object has the following fields.

Favorite Folder Object

A favorite folder object has the following fields.

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

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

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.

Any additional parameters will be ignored.

Any body attached to the request will be ignored.

Response

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

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"
  ]
}