RESTful APIs

zhenghaozNovember 20, 2022Less than 1 minute

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 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

Users API

POST /api/user

Insert a user.

Request Body

{
  "Comment": "per",
  "Labels": [
    "invoice",
    "plastic",
    "monte"
  ],
  "Subscribe": [
    "arsenic",
    "west",
    "magnetic"
  ],
  "UserId": "chicken"
}

Response Body

{
  "RowAffected": 1
}
GET /api/user/{user-id}

Get a user.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringID of the user to get

Response Body

{
  "Comment": "per",
  "Labels": [
    "invoice",
    "plastic",
    "monte"
  ],
  "Subscribe": [
    "arsenic",
    "west",
    "magnetic"
  ],
  "UserId": "chicken"
}
DELETE /api/user/{user-id}

Delete a user and his or her feedback.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringID of the user to delete

Response Body

{
  "RowAffected": 1
}
PATCH /api/user/{user-id}

Modify a user.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringID of the user to modify

Request Body

{
  "Comment": "copying",
  "Labels": [
    "indexing",
    "foolishly",
    "gender"
  ],
  "Subscribe": [
    "smart",
    "frozen",
    "vero"
  ]
}

Response Body

{
  "RowAffected": 1
}
GET /api/users

Get users.

Parameters

NameLocateTypeDescriptionRequired
nqueryintegerNumber of returned users
cursorquerystringCursor for the next page

Response Body

{
  "Cursor": "woot",
  "Users": [
    {
      "Comment": "per",
      "Labels": [
        "invoice",
        "plastic",
        "monte"
      ],
      "Subscribe": [
        "arsenic",
        "west",
        "magnetic"
      ],
      "UserId": "chicken"
    },
    {
      "Comment": "per",
      "Labels": [
        "invoice",
        "plastic",
        "monte"
      ],
      "Subscribe": [
        "arsenic",
        "west",
        "magnetic"
      ],
      "UserId": "chicken"
    },
    {
      "Comment": "per",
      "Labels": [
        "invoice",
        "plastic",
        "monte"
      ],
      "Subscribe": [
        "arsenic",
        "west",
        "magnetic"
      ],
      "UserId": "chicken"
    }
  ]
}
POST /api/users

Insert users.

Request Body

[
  {
    "Comment": "per",
    "Labels": [
      "invoice",
      "plastic",
      "monte"
    ],
    "Subscribe": [
      "arsenic",
      "west",
      "magnetic"
    ],
    "UserId": "chicken"
  },
  {
    "Comment": "per",
    "Labels": [
      "invoice",
      "plastic",
      "monte"
    ],
    "Subscribe": [
      "arsenic",
      "west",
      "magnetic"
    ],
    "UserId": "chicken"
  },
  {
    "Comment": "per",
    "Labels": [
      "invoice",
      "plastic",
      "monte"
    ],
    "Subscribe": [
      "arsenic",
      "west",
      "magnetic"
    ],
    "UserId": "chicken"
  }
]

Response Body

{
  "RowAffected": 1
}

Items API

POST /api/item

Insert an item. Overwrite if the item exists.

Request Body

{
  "Categories": [
    "veum",
    "turkmenistan",
    "confess"
  ],
  "Comment": "website",
  "IsHidden": false,
  "ItemId": "north",
  "Labels": [
    "hampshire",
    "jazz",
    "gosh"
  ],
  "Timestamp": "2022-11-01T12:34:31.378Z"
}

Response Body

{
  "RowAffected": 1
}
GET /api/item/{item-id}

Get a item.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringID of the item to get.

Response Body

{
  "Categories": [
    "veum",
    "turkmenistan",
    "confess"
  ],
  "Comment": "website",
  "IsHidden": false,
  "ItemId": "north",
  "Labels": [
    "hampshire",
    "jazz",
    "gosh"
  ],
  "Timestamp": "2022-11-01T12:34:31.378Z"
}
DELETE /api/item/{item-id}

Delete an item and its feedback.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringID of the item to delete

Response Body

{
  "RowAffected": 1
}
PATCH /api/item/{item-id}

Modify an item.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringID of the item to modify

Request Body

{
  "Categories": [
    "dodge",
    "content",
    "account"
  ],
  "Comment": "handcrafted",
  "IsHidden": false,
  "Labels": [
    "directional",
    "payment",
    "account"
  ],
  "Timestamp": "2022-10-16T00:07:11.105Z"
}

Response Body

{
  "RowAffected": 1
}
PUT /api/item/{item-id}/category/{category}

Insert a category for a item.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringID of the item to insert category
categorypathstringCategory to insert

Response Body

{
  "RowAffected": 1
}
DELETE /api/item/{item-id}/category/{category}

Delete a category from a item.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringID of the item to delete categoryßßß
categorypathstringCategory to delete

Response Body

{
  "RowAffected": 1
}
GET /api/items

Get items.

Parameters

NameLocateTypeDescriptionRequired
nqueryintegerNumber of returned items
cursorquerystringCursor for the next page

Response Body

{
  "Cursor": "nut",
  "Items": [
    {
      "Categories": [
        "veum",
        "turkmenistan",
        "confess"
      ],
      "Comment": "website",
      "IsHidden": false,
      "ItemId": "north",
      "Labels": [
        "hampshire",
        "jazz",
        "gosh"
      ],
      "Timestamp": "2022-11-01T12:34:31.378Z"
    },
    {
      "Categories": [
        "veum",
        "turkmenistan",
        "confess"
      ],
      "Comment": "website",
      "IsHidden": false,
      "ItemId": "north",
      "Labels": [
        "hampshire",
        "jazz",
        "gosh"
      ],
      "Timestamp": "2022-11-01T12:34:31.378Z"
    },
    {
      "Categories": [
        "veum",
        "turkmenistan",
        "confess"
      ],
      "Comment": "website",
      "IsHidden": false,
      "ItemId": "north",
      "Labels": [
        "hampshire",
        "jazz",
        "gosh"
      ],
      "Timestamp": "2022-11-01T12:34:31.378Z"
    }
  ]
}
POST /api/items

Insert items. Overwrite if items exist

Request Body

[
  {
    "Categories": [
      "veum",
      "turkmenistan",
      "confess"
    ],
    "Comment": "website",
    "IsHidden": false,
    "ItemId": "north",
    "Labels": [
      "hampshire",
      "jazz",
      "gosh"
    ],
    "Timestamp": "2022-11-01T12:34:31.378Z"
  },
  {
    "Categories": [
      "veum",
      "turkmenistan",
      "confess"
    ],
    "Comment": "website",
    "IsHidden": false,
    "ItemId": "north",
    "Labels": [
      "hampshire",
      "jazz",
      "gosh"
    ],
    "Timestamp": "2022-11-01T12:34:31.378Z"
  },
  {
    "Categories": [
      "veum",
      "turkmenistan",
      "confess"
    ],
    "Comment": "website",
    "IsHidden": false,
    "ItemId": "north",
    "Labels": [
      "hampshire",
      "jazz",
      "gosh"
    ],
    "Timestamp": "2022-11-01T12:34:31.378Z"
  }
]

Response Body

{
  "RowAffected": 1
}

Feedback API

GET /api/feedback

Get feedbacks.

Parameters

NameLocateTypeDescriptionRequired
cursorquerystringCursor for the next page
nqueryintegerNumber of returned feedback

Response Body

{
  "Cursor": "rhodium",
  "Feedback": [
    {
      "Comment": "boynton",
      "FeedbackType": "synthesizing",
      "ItemId": "copying",
      "Timestamp": "2022-01-12T13:38:15.748Z",
      "UserId": "keyboard"
    },
    {
      "Comment": "boynton",
      "FeedbackType": "synthesizing",
      "ItemId": "copying",
      "Timestamp": "2022-01-12T13:38:15.748Z",
      "UserId": "keyboard"
    },
    {
      "Comment": "boynton",
      "FeedbackType": "synthesizing",
      "ItemId": "copying",
      "Timestamp": "2022-01-12T13:38:15.748Z",
      "UserId": "keyboard"
    }
  ]
}
PUT /api/feedback

Insert feedbacks. Existed feedback will be overwritten.

Request Body

[
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  }
]

Response Body

{
  "RowAffected": 1
}
POST /api/feedback

Insert feedbacks. Ignore insertion if feedback exists.

Request Body

[
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  }
]

Response Body

{
  "RowAffected": 1
}
GET /api/feedback/{feedback-type}

Get feedbacks with feedback type.

Parameters

NameLocateTypeDescriptionRequired
feedback-typepathstringType of returned feedbacks
cursorquerystringCursor for the next page
nqueryintegerNumber of returned feedbacks

Response Body

{
  "Cursor": "rhodium",
  "Feedback": [
    {
      "Comment": "boynton",
      "FeedbackType": "synthesizing",
      "ItemId": "copying",
      "Timestamp": "2022-01-12T13:38:15.748Z",
      "UserId": "keyboard"
    },
    {
      "Comment": "boynton",
      "FeedbackType": "synthesizing",
      "ItemId": "copying",
      "Timestamp": "2022-01-12T13:38:15.748Z",
      "UserId": "keyboard"
    },
    {
      "Comment": "boynton",
      "FeedbackType": "synthesizing",
      "ItemId": "copying",
      "Timestamp": "2022-01-12T13:38:15.748Z",
      "UserId": "keyboard"
    }
  ]
}
GET /api/feedback/{feedback-type}/{user-id}/{item-id}

Get feedbacks between a user and a item with feedback type.

Parameters

NameLocateTypeDescriptionRequired
feedback-typepathstringType of returned feedbacks
user-idpathstringUser ID of returned feedbacks
item-idpathstringItem ID of returned feedbacks

Response Body

{
  "Comment": "boynton",
  "FeedbackType": "synthesizing",
  "ItemId": "copying",
  "Timestamp": "2022-01-12T13:38:15.748Z",
  "UserId": "keyboard"
}
DELETE /api/feedback/{feedback-type}/{user-id}/{item-id}

Delete feedbacks between a user and a item with feedback type.

Parameters

NameLocateTypeDescriptionRequired
feedback-typepathstringType of returned feedbacks
user-idpathstringUser ID of returned feedbacks
item-idpathstringItem ID of returned feedbacks

Response Body

{
  "Comment": "boynton",
  "FeedbackType": "synthesizing",
  "ItemId": "copying",
  "Timestamp": "2022-01-12T13:38:15.748Z",
  "UserId": "keyboard"
}
GET /api/feedback/{user-id}/{item-id}

Get feedbacks between a user and a item.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringUser ID of returned feedbacks
item-idpathstringItem ID of returned feedbacks

Response Body

[
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  }
]
DELETE /api/feedback/{user-id}/{item-id}

Delete feedbacks between a user and a item.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringUser ID of returned feedbacks
item-idpathstringItem ID of returned feedbacks

Response Body

[
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  }
]
GET /api/item/{item-id}/feedback

Get feedbacks by item id.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringItem ID of returned feedbacks

Response Body

[
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  }
]
GET /api/item/{item-id}/feedback/{feedback-type}

Get feedbacks by item id with feedback type.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringItem ID of returned feedbacks
feedback-typepathstringType of returned feedbacks

Response Body

[
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  }
]
GET /api/user/{user-id}/feedback

Get feedbacks by user id.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringUser ID of returned feedbacks

Response Body

[
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  }
]
GET /api/user/{user-id}/feedback/{feedback-type}

Get feedbacks by user id with feedback type.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringUser ID of returned feedbacks
feedback-typepathstringType of returned feedbacks

Response Body

[
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  },
  {
    "Comment": "boynton",
    "FeedbackType": "synthesizing",
    "ItemId": "copying",
    "Timestamp": "2022-01-12T13:38:15.748Z",
    "UserId": "keyboard"
  }
]

Recommendation API

GET /api/item/{item-id}/neighbors

get neighbors of a item

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringID of the item to get neighbors
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items

Response Body

[
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  }
]
GET /api/item/{item-id}/neighbors/{category}

Get neighbors of a item in category.

Parameters

NameLocateTypeDescriptionRequired
item-idpathstringID of the item to get neighbors
categorypathstringCategory of returned items
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items

Response Body

[
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  }
]
GET /api/latest

Get the latest items.

Parameters

NameLocateTypeDescriptionRequired
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items
user-idquerystringRemove read items of a user

Response Body

[
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  }
]
GET /api/latest/{category}

Get the latest items in category.

Parameters

NameLocateTypeDescriptionRequired
categorypathstringCategory of returned items.
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items
user-idquerystringRemove read items of a user

Response Body

[
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  }
]
GET /api/popular

Get popular items.

Parameters

NameLocateTypeDescriptionRequired
nqueryintegerNumber of returned recommendations
offsetqueryintegerOffset of returned recommendations
user-idquerystringRemove read items of a user

Response Body

[
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  }
]
GET /api/popular/{category}

Get popular items in category.

Parameters

NameLocateTypeDescriptionRequired
categorypathstringCategory of returned items.
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items
user-idquerystringRemove read items of a user

Response Body

[
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  }
]
GET /api/recommend/{user-id}

Get recommendation for user.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringID of the user to get recommendation
write-back-typequerystringType of write back feedback
write-back-delayquerystringTimestamp delay of write back feedback (format 0h0m0s)
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items

Response Body

[
  "hacking",
  "east",
  "north"
]
GET /api/recommend/{user-id}/{category}

Get recommendation for user.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringID of the user to get recommendation
categorypathstringCategory of the returned items
write-back-typequerystringType of write back feedback
write-back-delayquerystringTimestamp delay of write back feedback (format 0h0m0s)
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items

Response Body

[
  "division",
  "manager",
  "reggae"
]
POST /api/session/recommend

Get recommendation for session.

Parameters

NameLocateTypeDescriptionRequired
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items

Request Body

[
  {
    "Comment": "magenta",
    "FeedbackType": "west",
    "ItemId": "chlorine",
    "Timestamp": "nissan",
    "UserId": "chevrolet"
  },
  {
    "Comment": "magenta",
    "FeedbackType": "west",
    "ItemId": "chlorine",
    "Timestamp": "nissan",
    "UserId": "chevrolet"
  },
  {
    "Comment": "magenta",
    "FeedbackType": "west",
    "ItemId": "chlorine",
    "Timestamp": "nissan",
    "UserId": "chevrolet"
  }
]

Response Body

[
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  }
]
POST /api/session/recommend/{category}

Get recommendation for session.

Parameters

NameLocateTypeDescriptionRequired
categorypathstringCategory of the returned items
nqueryintegerNumber of returned items
offsetqueryintegerOffset of returned items

Request Body

[
  {
    "Comment": "magenta",
    "FeedbackType": "west",
    "ItemId": "chlorine",
    "Timestamp": "nissan",
    "UserId": "chevrolet"
  },
  {
    "Comment": "magenta",
    "FeedbackType": "west",
    "ItemId": "chlorine",
    "Timestamp": "nissan",
    "UserId": "chevrolet"
  },
  {
    "Comment": "magenta",
    "FeedbackType": "west",
    "ItemId": "chlorine",
    "Timestamp": "nissan",
    "UserId": "chevrolet"
  }
]

Response Body

[
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  }
]
GET /api/user/{user-id}/neighbors

Get neighbors of a user.

Parameters

NameLocateTypeDescriptionRequired
user-idpathstringID of the user to get neighbors
nqueryintegerNumber of returned users
offsetqueryintegerOffset of returned users

Response Body

[
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  },
  {
    "Id": "gasoline",
    "Score": 0.7340646507275475
  }
]

Health API

GET /api/health/live

Probe the liveness of this node. Return OK once the server starts.

Response Body

{
  "CacheStoreConnected": false,
  "CacheStoreError": "I Can't Get Next to You",
  "DataStoreConnected": false,
  "DataStoreError": "My Girl",
  "Ready": false
}
GET /api/health/ready

Probe the readiness of this node. Return OK if the server is able to handle requests.

Response Body

{
  "CacheStoreConnected": false,
  "CacheStoreError": "I Can't Get Next to You",
  "DataStoreConnected": false,
  "DataStoreError": "My Girl",
  "Ready": false
}
Loading...