RESTful APIs

7/24/22About 7 min

RESTful APIs

RESTful APIs provided by the Gorse server are listed in this section. For more detailed information, please browse the interactive API document at:

http://<server_node_IP>:<server_node_port>/apidocs.

Authorization

By default, there is no authorization required for RESTful APIs. Authorization can be enabled by set api_key in the config file. The API key is passed through X-API-Key header.

curl -H "X-API-Key: *****"  http://127.0.0.1:8087/api/recommend/bob?n=10

Tips

The API key is defined in the [server] section in the configuration file:

[server]

# Secret key for RESTful APIs (SSL required).
api_key = ""

API Endpoints

GET /api/collaborative-filtering/{user-id} Get collaborative filtering recommendation for a user.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
user-id	path	string	User ID
n	query	integer	Number of returned items
offset	query	integer	Offset of returned items
category	query	string	Category of returned items.
user-id	query	string	Remove read items of a user

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

GET /api/feedback List feedbacks.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
cursor	query	string	Cursor for the next page
n	query	integer	Number of returned feedback

Response:

{
  "Cursor": "string",
  "Feedback": [
    {
      "Comment": "string",
      "FeedbackType": "string",
      "ItemId": "string",
      "Timestamp": "2000-01-01T00:00:00Z",
      "Updated": "2000-01-01T00:00:00Z",
      "UserId": "string",
      "Value": 0
    }
  ]
}

PUT /api/feedback Insert feedbacks. Existed feedback will be overwritten.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key

Body:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "2000-01-01T00:00:00Z",
    "Updated": "2000-01-01T00:00:00Z",
    "UserId": "string",
    "Value": 0
  }
]

Response:

{
  "RowAffected": 0
}

POST /api/feedback Insert feedbacks. Accumulate value if feedback already exists.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key

Body:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "2000-01-01T00:00:00Z",
    "Updated": "2000-01-01T00:00:00Z",
    "UserId": "string",
    "Value": 0
  }
]

Response:

{
  "RowAffected": 0
}

GET /api/feedback/{feedback-type} List feedbacks with feedback type.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
feedback-type	path	string	Feedback type
cursor	query	string	Cursor for the next page
n	query	integer	Number of returned feedbacks

Response:

{
  "Cursor": "string",
  "Feedback": [
    {
      "Comment": "string",
      "FeedbackType": "string",
      "ItemId": "string",
      "Timestamp": "2000-01-01T00:00:00Z",
      "Updated": "2000-01-01T00:00:00Z",
      "UserId": "string",
      "Value": 0
    }
  ]
}

GET /api/feedback/{feedback-type}/{user-id}/{item-id} Get feedbacks between a user and a item with feedback type.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
feedback-type	path	string	Feedback type
user-id	path	string	User ID
item-id	path	string	Item ID

Response:

{
  "Comment": "string",
  "FeedbackType": "string",
  "ItemId": "string",
  "Timestamp": "2000-01-01T00:00:00Z",
  "Updated": "2000-01-01T00:00:00Z",
  "UserId": "string",
  "Value": 0
}

DELETE /api/feedback/{feedback-type}/{user-id}/{item-id} Delete feedbacks between a user and a item with feedback type.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
feedback-type	path	string	Feedback type
user-id	path	string	User ID
item-id	path	string	Item ID

Response:

{
  "RowAffected": 0
}

GET /api/feedback/{user-id}/{item-id} List feedbacks between a user and a item.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
user-id	path	string	User ID
item-id	path	string	Item ID

Response:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "2000-01-01T00:00:00Z",
    "Updated": "2000-01-01T00:00:00Z",
    "UserId": "string",
    "Value": 0
  }
]

DELETE /api/feedback/{user-id}/{item-id} Delete feedbacks between a user and a item.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
user-id	path	string	User ID
item-id	path	string	Item ID

Response:

{
  "RowAffected": 0
}

GET /api/health/live Probe the liveness of this node. Return OK once the server starts.

Parameters: None

Response:

{
  "CacheStoreConnected": false,
  "CacheStoreError": {},
  "DataStoreConnected": false,
  "DataStoreError": {},
  "Ready": false
}

GET /api/health/ready Probe the readiness of this node. Return OK if the server is able to handle requests.

Parameters: None

Response:

{
  "CacheStoreConnected": false,
  "CacheStoreError": {},
  "DataStoreConnected": false,
  "DataStoreError": {},
  "Ready": false
}

POST /api/item Insert an item.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key

Body:

{
  "Categories": [
    "string"
  ],
  "Comment": "string",
  "IsHidden": false,
  "ItemId": "string",
  "Labels": {},
  "Timestamp": "2000-01-01T00:00:00Z"
}

Response:

{
  "RowAffected": 0
}

GET /api/item-to-item/{name}/{item-id} Get item-to-item recommendation.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
name	path	string	Name of the item-to-item recommendation
item-id	path	string	Item ID
n	query	integer	Number of returned items
offset	query	integer	Offset of returned items
category	query	string	Category of returned items
user-id	query	string	Remove read items of a user

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

GET /api/item/{item-id} Get an item.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
item-id	path	string	Item ID.

Response:

{
  "Categories": [
    "string"
  ],
  "Comment": "string",
  "IsHidden": false,
  "ItemId": "string",
  "Labels": {},
  "Timestamp": "2000-01-01T00:00:00Z"
}

DELETE /api/item/{item-id} Delete an item and its feedback.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
item-id	path	string	Item ID

Response:

{
  "RowAffected": 0
}

PATCH /api/item/{item-id} Modify an item.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
item-id	path	string	Item ID

Body:

{
  "Categories": [
    "string"
  ],
  "Comment": "string",
  "IsHidden": false,
  "Labels": {},
  "Timestamp": "2000-01-01T00:00:00Z"
}

Response:

{
  "RowAffected": 0
}

PUT /api/item/{item-id}/category/{category} Insert a category for a item.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
item-id	path	string	Item ID
category	path	string	Category to insert

Response:

{
  "RowAffected": 0
}

DELETE /api/item/{item-id}/category/{category} Delete a category from a item.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
item-id	path	string	Item ID
category	path	string	Category to delete

Response:

{
  "RowAffected": 0
}

GET /api/item/{item-id}/feedback Get feedbacks by item id.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
item-id	path	string	Item ID

Response:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "2000-01-01T00:00:00Z",
    "Updated": "2000-01-01T00:00:00Z",
    "UserId": "string",
    "Value": 0
  }
]

GET /api/item/{item-id}/feedback/{feedback-type} Get feedbacks by item id with feedback type.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
item-id	path	string	Item ID
feedback-type	path	string	Feedback type

Response:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "2000-01-01T00:00:00Z",
    "Updated": "2000-01-01T00:00:00Z",
    "UserId": "string",
    "Value": 0
  }
]

GET /api/item/{item-id}/neighbors Get neighbors of a item

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
item-id	path	string	Item ID
n	query	integer	Number of returned items
offset	query	integer	Offset of returned items
category	query	string	Category of returned items
user-id	query	string	Remove read items of a user

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

GET /api/items List items.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
n	query	integer	Number of returned items
cursor	query	string	Cursor for the next page

Response:

{
  "Cursor": "string",
  "Items": [
    {
      "Categories": [
        "string"
      ],
      "Comment": "string",
      "IsHidden": false,
      "ItemId": "string",
      "Labels": {},
      "Timestamp": "2000-01-01T00:00:00Z"
    }
  ]
}

POST /api/items Insert items.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key

Body:

[
  {
    "Categories": [
      "string"
    ],
    "Comment": "string",
    "IsHidden": false,
    "ItemId": "string",
    "Labels": {},
    "Timestamp": "2000-01-01T00:00:00Z"
  }
]

Response:

{
  "RowAffected": 0
}

GET /api/latest Get latest items.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
category	query	string	Category of returned items
n	query	integer	Number of returned items
offset	query	integer	Offset of returned items
user-id	query	string	Remove read items of a user

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

GET /api/non-personalized/{name} Get non-personalized recommendations.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
category	query	string	Category of returned items.
n	query	integer	Number of returned users
offset	query	integer	Offset of returned users
user-id	query	string	Remove read items of a user

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

GET /api/recommend/{user-id} Get recommendation for user.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
user-id	path	string	User ID
category	query	string	Category of the returned items (support multi-categories filtering)
write-back-type	query	string	Type of write back feedback
write-back-delay	query	string	Timestamp delay of write back feedback (format 0h0m0s)
n	query	integer	Number of returned items
offset	query	integer	Offset of returned items

Response:

[
  "string"
]

POST /api/session/recommend Get recommendation for session.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
n	query	integer	Number of returned items
offset	query	integer	Offset of returned items

Body:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "string",
    "UserId": "string",
    "Value": 0
  }
]

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

POST /api/user Insert a user.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key

Body:

{
  "Comment": "string",
  "Labels": {},
  "UserId": "string"
}

Response:

{
  "RowAffected": 0
}

GET /api/user-to-user/{name}/{user-id} Get user-to-user recommendation.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
name	path	string	Name of the user-to-user recommendation
user-id	path	string	User ID
n	query	integer	Number of returned users
offset	query	integer	Offset of returned users

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

GET /api/user/{user-id} Get a user.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
user-id	path	string	User ID

Response:

{
  "Comment": "string",
  "Labels": {},
  "UserId": "string"
}

DELETE /api/user/{user-id} Delete a user. His or her feedback will also be deleted.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
user-id	path	string	User ID

Response:

{
  "RowAffected": 0
}

PATCH /api/user/{user-id} Modify a user.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
user-id	path	string	User ID

Body:

{
  "Comment": "string",
  "Labels": {}
}

Response:

{
  "RowAffected": 0
}

GET /api/user/{user-id}/feedback Get feedbacks by user id.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
user-id	path	string	User ID

Response:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "2000-01-01T00:00:00Z",
    "Updated": "2000-01-01T00:00:00Z",
    "UserId": "string",
    "Value": 0
  }
]

GET /api/user/{user-id}/feedback/{feedback-type} Get feedbacks by user id with feedback type.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
user-id	path	string	User ID
feedback-type	path	string	Feedback type

Response:

[
  {
    "Comment": "string",
    "FeedbackType": "string",
    "ItemId": "string",
    "Timestamp": "2000-01-01T00:00:00Z",
    "Updated": "2000-01-01T00:00:00Z",
    "UserId": "string",
    "Value": 0
  }
]

GET /api/user/{user-id}/neighbors Get neighbors of a user.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
user-id	path	string	User ID
n	query	integer	Number of returned users
offset	query	integer	Offset of returned users

Response:

[
  {
    "Id": "string",
    "Score": 0
  }
]

GET /api/users List users.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key
n	query	integer	Number of returned users
cursor	query	string	Cursor for the next page

Response:

{
  "Cursor": "string",
  "Users": [
    {
      "Comment": "string",
      "Labels": {},
      "UserId": "string"
    }
  ]
}

POST /api/users Insert users.

Parameters:

Name	In	Type	Description
X-API-Key	header	string	API key

Body:

[
  {
    "Comment": "string",
    "Labels": {},
    "UserId": "string"
  }
]

Response:

{
  "RowAffected": 0
}