API endpoints
FA01 | Create bookmark
POST | /favourites/bookmarks |
|---|
User permission required
Remarks
- The parameter folderId defines all lists (folders) to add the bookmark.
- Duplicates for folderIds are not possible because of using a set.
- The folderId favorites is always used. If no folderId is specified, only favorites is used.
- If the folder favorites not exists, because a new user adds the first bookmark, then the folder favorites is created.
Query parameters
| Name | Value | Occurence | Default |
|---|---|---|---|
| folderIds | ID of folder(s) | Multiple | - |
Request payload
Returns Bookmark JSON object:
{
"id": "rjzgAIgBdHmpxQQKvQHm", // Not used
"itemId": "IVMX3IRHKU725WR2HHT6VY2AFFS72FGK", // Required
"description": "My important description", // Optional
"userId": "fachstelle_museum", // Not used
"type": "CULTURAL_ITEM", // Required
"createdAt": 1683641908448, // Not used
"updatedAt": 1683641908448, // Not used
"keywordTool": { // Optional
"done": true
}
}Response payload
Returns Bookmark JSON object:
{
"id": "rjzgAIgBdHmpxQQKvQHm",
"itemId": "IVMX3IRHKU725WR2HHT6VY2AFFS72FGK",
"description": "My important description",
"userId": "fachstelle_museum",
"type": "CULTURAL_ITEM",
"createdAt": 1683641908448,
"updatedAt": 1683641908448,
"keywordTool": {
"done": true
}
}
Status codes
- 200 = Bookmark created
- 400 = Item Id is missing (required)
- 401 = User is not authorized
- 500 = Internal server error
Related Use Case(s)
- UC01 | Create bookmark
- The user selects an object from an object list as a favorite.
- The user selects an object from an object list as a favorite.
Example call(s)
- Create bookmark in only main folder
- GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/bookmarks
- Create bookmark in main folder and two additional folders
- GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/bookmarks?folderIds=Sjszo4cBdHmpxQQKUvah&folderIds=rjwQKYgBdHmpxQQKKgSs
FA02 | Retrieve bookmark
GET | /favourites/bookmarks/{id} |
|---|
User permission required
Query parameters
FA03 | Retrieve bookmarks
GET | /favourites/bookmarks |
|---|
User permission required
Query parameters
| Name | Value | Occurence | Default |
|---|---|---|---|
| folderIds | ID of folder(s) | Multiple | - |
FA04 | Update bookmark
PUT | /favourites/bookmarks/{id} |
|---|
User permission required
Remarks
- The parameter folderId defines all lists (folders) to add the bookmark.
- Duplicates for folderIds are not possible because of using a set.
- The folderId favorites is always used. If no folderId is specified, only favorites is used.
- If the folder favorites not exists, because a new user adds the first bookmark, then the folder favorites is created.
Query parameters
| Name | Value | Occurence | Default |
|---|---|---|---|
| userId | ID of user | Once | - |
| itemIds | List of IDs | Multiple | - |
| offset | Beginn offset of results | Once | -1 |
| size | Size data of results | Once | -1 |
FA05 | Delete bookmark
DELETE | /favourites/bookmarks/{id} |
|---|
User permission required
Query parameters
| Name | Value | Occurence | Default |
|---|---|---|---|
| folderIds | ID of folder(s) | Multiple | - |
FA06 | Create folder
POST | /favourites/folders |
|---|
User permission required
Query parameters
FA07 | Add bookmark to folder
POST | /favourites/{id}/bookmarks |
|---|
User permission required
Remarks
- A bookmark could not be added to the main folder (favorites), because it is added to this folder when you create a bookmark.
- The folder ID and bookmark ID must exist before adding something.
Query parameters
| Name | Value | Occurence | Default |
|---|---|---|---|
| bookmarkId | ID of bookmark to add | Once | - |
FA08 | Retrieve folder
GET | /favourites/folders/{id} |
|---|
User permission required
Query parameters
FA09 | Retrieve bookmarks of a folder
GET | /favourites/folders/{id}/bookmarks |
|---|
User permission required
Query parameters
FA10 | Retrieve folders
GET | /favourites/folders |
|---|
User permission required
Query parameters
| Name | Value | Occurence | Default |
|---|---|---|---|
| userId | ID of user | Once | - |
| title | Title of folder | Once | - |
| offset | Beginn offset of results | Once | -1 |
| size | Size data of results | Once | -1 |
Query parameters
FA11 | Update folder
POST | /favourites/folders/{id} |
|---|
User permission required
Query parameters
| Name | Value | Occurence |
|---|---|---|
| folderIds | ID of folder(s) | Multiple |
FA12 | Delete folder
DELETE | /favourites/folders/{id} |
|---|
User permission required
Query parameters
| Name | Value | Occurence |
|---|---|---|
| folderIds | ID of folder(s) | Multiple |
FA13 | Delete bookmark from folder
DELETE | /favourites/folders/{id}/bookmarks/{bookmarkId} |
|---|
User permission required
Remarks
- A bookmark could not be deleted from the main folder (favorites), because this is done only if the bookmark is deleted (see Delete Bookmark).
- The folder ID and bookmark ID must exist before deleting something.
Query parameters
FA14 | Delete all bookmarks and folders
DELETE | /favourites/folders |
|---|
User permission required
Query parameters
| Name | Value | Occurence | Default |
|---|---|---|---|
| userId | ID of user to delete | Once | - |