Favorites API

This document describes the v2 Favorites API of Fess. For the common response envelope, error model, and CSRF, see API Overview.

The base URL is http://<Server Name>/api/v2/ (local environment example: http://localhost:8080/api/v2).

Note

To use the favorites feature, the user.favorite setting must be enabled.

Fetching Favorite Documents List

Request

HTTP Method GET
Endpoint /api/v2/favorites

Returns the IDs of documents that the calling user has previously added to favorites, among search results identified by query_id. query_id is the opaque identifier (query_id field) returned by the search API (/search).

An anonymous caller (no user code associated with the session) results in auth_required (401). When the user.favorite feature is disabled, it returns invalid_request (400). When query_id does not match a cached result set in the session, it returns 200 with an empty data array.

Request Parameters

Request Parameters
query_id The opaque query_id returned by the search API (/search) (query, required, str).

Table: Request Parameters

Response

On success (200), the following fields are returned directly under response in the common envelope.

{
  "response": {
    "status": 0,
    "record_count": 2,
    "data": [
      { "doc_id": "a1b2c3d4e5f6" },
      { "doc_id": "f6e5d4c3b2a1" }
    ]
  }
}

Each field is described below.

Response Fields
record_count Number of favorite documents in data (int).
data Array of favorite documents in the queried result set, preserving search result order. Each element is {doc_id}.

Table: Response Fields

Error Response

For details on the error model, see API Overview. The HTTP statuses returned by this endpoint are as follows.

Error Response
Status Code Description
400 Bad Request The request is invalid (including when the user.favorite feature is disabled).
401 Unauthorized Authentication is required (anonymous caller).
405 Method Not Allowed The HTTP method is not allowed.
500 Internal Server Error An internal server error occurred.

Table: Error Response

Fetching Favorite Status

Request

HTTP Method GET
Endpoint /api/v2/documents/{docId}/favorite

Retrieves the favorite status of the specified document.

Request Parameters

Request Parameters
docId Document identifier (path, required, pattern ^[A-Za-z0-9_-]+$).

Table: Request Parameters

Response

On success (200), the following fields are returned directly under response in the common envelope.

{
  "response": {
    "status": 0,
    "doc_id": "a1b2c3d4e5f6",
    "favorite": true,
    "count": 5
  }
}

Each field is described below.

Response Fields
doc_id Document ID (str).
favorite Whether the calling user has favorited this document (bool).
count Total favorite count for this document (int64).

Table: Response Fields

Error Response

For details on the error model, see API Overview. The HTTP statuses returned by this endpoint are as follows.

Error Response
Status Code Description
400 Bad Request The request is invalid.
404 Not Found The resource was not found.
405 Method Not Allowed The HTTP method is not allowed.
500 Internal Server Error An internal server error occurred.

Table: Error Response

Adding a Favorite

Request

HTTP Method POST
Endpoint /api/v2/documents/{docId}/favorite

Adds the specified document to favorites. Since this is a state-changing request, the X-Fess-CSRF-Token header is required (see API Overview).

Request Parameters

Request Parameters
docId Document identifier (path, required, pattern ^[A-Za-z0-9_-]+$).

Table: Request Parameters

Request Body

Send a JSON (FavoritePostRequest) with Content-Type: application/json containing the following fields.

{
  "query_id": "f8b1c2d3e4a5"
}
Request Body
query_id The opaque query_id returned by the search API (/search) (str, required).

Table: Request Body

Response

On success (200), the following fields are returned directly under response in the common envelope.

{
  "response": {
    "status": 0,
    "doc_id": "a1b2c3d4e5f6",
    "ok": true,
    "favorite": true,
    "count": 6,
    "already_existed": false
  }
}

Each field is described below.

Response Fields
doc_id Document ID (str).
ok Always true (bool).
favorite Always true (bool). Whether a new addition or an existing one, the document becomes a favorite of the calling user.
count Current favorite count after the operation (int64). For a new addition, optimistically count + 1 before update; for an idempotent re-POST, reflects the stored count.
already_existed true if the favorite had been registered previously (bool, idempotent re-POST). Not present in the initial POST that newly registers a favorite.

Table: Response Fields

Error Response

For details on the error model, see API Overview. The HTTP statuses returned by this endpoint are as follows.

Error Response
Status Code Description
400 Bad Request The request is invalid.
401 Unauthorized Authentication is required.
403 Forbidden Not permitted due to missing or expired CSRF token.
404 Not Found The resource was not found.
405 Method Not Allowed The HTTP method is not allowed.
413 Payload Too Large The request body exceeds the size limit.
415 Unsupported Media Type The Content-Type is not supported.
500 Internal Server Error An internal server error occurred.

Table: Error Response