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 folder favorites not exists, because a new user adds the first bookmark, then the folder favorites is created.
Query parameters
Name | Value | Occurence | Default | Mandatory |
---|---|---|---|---|
folderIds | ID of folder(s) | Multiple | - | Yes, at least one id |
Response payload
Status codes
- 200 = Bookmark created
- 400 = Item Id is missing (required) or at least one folder id is missing
- 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 main folder and two additional folders
- POST https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/bookmarks?folderIds=Sjszo4cBdHmpxQQKUvah&folderIds=rjwQKYgBdHmpxQQKKgSs
FA02 | Retrieve bookmark
GET | /favourites/bookmarks/{id} |
---|
User permission required
Response payload
Status codes
- 200 = Bookmark found
- 401 = User is not authorized
- 404 = Bookmark ID not found
- 500 = Internal server error
Related Use Case(s)
- All info of a bookmark is retrieved to display it in the frontend.
Example call(s)
- Retrieve bookmark
- GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/bookmarks/YzxuJIsBdHmpxQQKPSya
FA03 | Retrieve bookmarks (Deprecated)
GET | /favourites/bookmarks |
---|
User permission required
Query parameters
Name | Value | Occurence | Default |
---|---|---|---|
userId | ID of user | Once | - |
itemIds | IDs of items | Multiple | - |
offset | Offset of result | Once | -1 |
size | Length of result | Once | -1 |
Response payload
Status codes
- 200 = Bookmark(s) found
- 400 = Missing some search params
- 401 = User not authorized
- 500 = Internal server error
Related Use Case(s)
- Bookmarks according to certain criteria are retrieved to be displayed in the frontend.
Example call(s)
- Retrieve all bookmarks by user
- GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/bookmarks?userId=fachstelle_museum
- Retrieve all bookmarks by user and item ids
- GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/bookmarks?userId=fachstelle_museum&itemIds=itemId________________________01
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.
Request payload
Response payload
Status codes
- 200 = Bookmark updated
- 401 = User is not authorized
- 404 = Bookmark ID not found
- 500 = Internal server error
Related Use Case(s)
- UC07 | Change bookmark description
- A user changes the description of a bookmark.
- A user changes the description of a bookmark.
Example call(s)
- Update bookmark
- PUT https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/bookmarks/YzxuJIsBdHmpxQQKPSya
FA05 | Delete bookmark
DELETE | /favourites/bookmarks/{id} |
---|
User permission required
Status codes
- 200 = Bookmark deleted
- 401 = User is not authorized
- 404 = Bookmark ID not found
- 500 = Internal server error
Related Use Case(s)
- UC06 | Delete bookmarks in All Favorites
- A user deletes a bookmark from favorites (and the rest of the lists).
- A user deletes a bookmark from favorites (and the rest of the lists).
Example call(s)
- Delete bookmark
- DELETE https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/bookmarks/ZTxuJIsBdHmpxQQKUSwX
FA06 | Create folder
POST | /favourites/folders |
---|
User permission required
Request payload
Response payload
Status codes
- 200 = Folder created
- 400 = Title attribute is missing or Portal attribute is wrong
- 401 = User is not authorized
- 409 = Folder already exists
- 500 = Internal server error
Related Use Case(s)
- UC05 | Add personal folder
- A user creates a personal folder.
- A user creates a personal folder.
Example call(s)
- Create folder
- POST https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders
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 | - |
Status codes
- 200 = Bookmarks added
- 400 = Bookmark ID not exist
- 401 = User is not authorized
- 404 = Folder ID not exist
- 500 = Internal server error
Related Use Case(s)
- UC02 | Assign bookmarks to selected lists
- A user stores bookmarks (additionally) in personal lists.
- UC08 | Copy bookmarks from All Favorites to personal lists
- A user copies bookmarks into personal lists.
- UC14 | Copy bookmarks to another personal list
- A user copies bookmarks from a personal list to other personal lists.
- A user copies bookmarks from a personal list to other personal lists.
Example call(s)
- Add bookmark to folder
- POST https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/ZjxwJIsBdHmpxQQKjyxB/bookmarks?bookmarkId=ZTxuJIsBdHmpxQQKUSwX
FA08 | Retrieve folder
GET | /favourites/folders/{id} |
---|
User permission required
Response payload
Status codes
- 200 = Folder found
- 401 = User is not authorized
- 404 = Folder not exist
- 500 = Internal server error
Related Use Case(s)
- All info of a list is retrieved to display it in the frontend.
Example call(s)
- Retrieve folder
- GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/ZjxwJIsBdHmpxQQKjyxB
FA09 | Retrieve bookmarks of a folder
GET | /favourites/folders/{id}/bookmarks |
---|
User permission required
Response payload
Status codes
- 200 = Folder found
- 401 = User not authorized
- 404 = Folder not exist
- 500 = Internal server error
Related Use Case(s)
- UC04 | Retrieve bookmarks of a list
- The user retrieves bookmarks of a specified list.
- The user retrieves bookmarks of a specified list.
Example call(s)
- Retrieve bookmarks of folder
- GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/vJ2GGYsBYUgoK0Rzg70n/bookmarks
FA10 | Retrieve folders
GET | /favourites/folders |
---|
User permission required
Query parameters
Name | Value | Occurence | Default |
---|---|---|---|
userId | ID of user | Once | - |
portal | Name of used portal | Once | DDB |
title | Title of folder | Once | - |
offset | Beginn offset of results | Once | -1 |
size | Size data of results | Once | -1 |
Response payload
Status codes
- 200 = Folder(s) found
- 400 = Missing some search params
- 401 = User not authorized
- 500 = Internal server error
Related Use Case(s)
- UC03 | Listennamen eines Benutzers abrufen
- The user retrieves bookmarks of a specified list.
- The user retrieves bookmarks of a specified list.
Example call(s)
- Retrieve folder by user
- GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders?userId=fachstelle_museum&portal=DDB
- Retrieve folder by user and title
- GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders?userId=fachstelle_museum&portal=DDB&title=favorites
FA11 | Update folder
POST | /favourites/folders/{id} |
---|
User permission required
Request payload
Response payload
Status codes
- 200 = Folder updated
- 401 = User not authorized
- 404 = Folder ID not found
- 500 = Internal server error
Related Use Case(s)
- UC09 | Publish or privatize personal list
- A user publishes a list or make a published list private again.
- UC10 | Change properties of personal list
- Furthermore, the user can change name, description, private/public, name abbreviation of a personal list.
- Furthermore, the user can change name, description, private/public, name abbreviation of a personal list.
Example call(s)
- Update folder
- POST https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/wJ2JGYsBYUgoK0RzI71_
FA12 | Delete folder
DELETE | /favourites/folders/{id} |
---|
User permission required
Status codes
- 200 = Folder deleted
- 400 = Folder favorite could not be deleted
- 401 = User not authorized
- 404 = Folder ID not found
- 500 = Internal server error
Related Use Case(s)
- UC11 | Remove personal list with bookmarks
- The user deletes a personal list with the contained bookmarks.
- The user deletes a personal list with the contained bookmarks.
Example call(s)
- Delete folder
- DELETE https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/wJ2JGYsBYUgoK0RzI71_
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.
Status codes
- 200 = Bookmark in Folder deleted
- 400 = Bookmark ID not found
- 401 = User not authorized
- 404 = Folder ID not found
- 500 = Internal server error
Related Use Case(s)
- FA13 | Delete bookmark from list
- A bookmark is removed from a personal list.
- A bookmark is removed from a personal list.
Example call(s)
- Delete bookmarks from folder
- DELETE https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/wJ2JGYsBYUgoK0RzI71_/bookmarks/vp2GGYsBYUgoK0Rzh71c
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 | - |
Status codes
- 200 = Bookmarks and Folders deleted
- 401 = User not authorized
- 404 = User ID not found
- 500 = Internal server error
Related Use Case(s)
- A user deletes his account. Then the system first deletes all bookmarks in all lists of the user. Then all lists including favorites are deleted.
Example call(s)
- Delete all bookmarks and folders
- DELETE https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders?userId=fachstelle_museum
API calls for Use Cases
UC01 | Add bookmark
Description
- A user performs a search and a hit list appears. Now the user saves the object item as a bookmark.
- The bookmark is always first saved in the main folder (favorites).
API mapping
- FA01 | Create bookmark
- POST /favourites/bookmarks
- Send Bookmark-JSON in body
- POST /favourites/bookmarks
UC02 | Assign bookmarks to selected lists
Description
- After saving a bookmark for the first time in favorites, a dialog appears that allows a user to continue adding the bookmark to other personal lists.
- For this purpose, the user can select and confirm the additional desired lists.
API mapping
- FA10 | Get all folders of a user
- GET /favourites/folders?userId={userID}
- Receive a FolderResult-JSON with all folders
- FA07 | Add bookmark to list
- POST /favourites/folders/{folderID}/bookmarks/{bookmarkID}
- GET /favourites/folders?userId={userID}
UC03 | Retrieve names of a user listDescription
- After clicking favorites link in DDB a user should see his favorite lists to select one.
API mapping
- FA10 | Get all folders of a user
- GET /favourites/folders?userId={userID}
UC04 | Retrieve bookmarks of a list
Description
- A user want to see a list and so he clicks to one of his lists.
API mapping
- FA09 | Retrieve bookmarks of a list
- GET /favourites/folders/{folderID}/bookmarks
UC05 | Add personal list
Description
- A user creates a additional personal list.
API mapping
- FA06 | Create list
- POST /favourites/folders
- Send Folder-JSON in body
- POST /favourites/folders
UC06 | Delete bookmark
Description
- A user deletes a bookmark in favorites, and so it will also be deleted in each of the personal lists.
API mapping
- FA05 | Delete bookmark
- DELETE /favourites/bookmarks/{bookmarkID}
UC07 | Change bookmark description
Description
- A user adds, deletes or modifies the description of a bookmark.
API mapping
- FA04 | Update bookmark (set only changes)
- PUT /favourites/bookmarks/{bookmarkID}
- Send Bookmark-JSON in body
- PUT /favourites/bookmarks/{bookmarkID}
UC08 | Copy bookmarks from All Favorites to personal lists
Description
- A user copies a bookmark from the main list (favorites) to personal lists.
API mapping
- FA07 | Add bookmark to another lists
- POST /favourites/folders/{folderID}/bookmarks?bookmarkId={bookmarkID}
UC09 | Publish or privatize personal list
Description
- A user publishes a list or make a published list private again.
API mapping
- FA08 | Get list with properties
- GET /favourites/folders/{folderID}
- FA11 | Update list (set only changes)
- POST /favourites/folders/{folderID}
- Send Folder-JSON in body
- POST /favourites/folders/{folderID}
UC10 | Change properties of personal list
Description
- A user changes name, description, published/unpublished, name abbreviation from one of his personal lists.
API mapping
- FA08 | Get list
- GET /favourites/folders/{folderID}
- FA11 | Update list (set only changes)
- POST /favourites/folders/{folderID}
- Send Folder-JSON in body
- POST /favourites/folders/{folderID}
UC11 | Remove personal list with bookmarks
Description
- A user deletes a personal list with the contained bookmarks. However, only the assignment of the bookmarks to the list is deleted.
API mapping
- FA12 | Delete list
- DELETE /favourites/folders/{folderID}
UC12 | Remove personal list and contained bookmarks in all lists
Description
- A user additional deletes containing bookmarks of the list, also from all other lists, including the main list (favorites).
API mapping
- FA12 | Delete list
- DELETE /favourites/folders/{folderID}
UC13 | Remove bookmark in personal list
Description
- A user deletes a bookmark from a personal list.
API mapping
- FA13 | Remove bookmark from list
- DELETE /favourites/folders/{folderID}/bookmarks/{bookmarkID}
UC14 | Copy bookmarks to other personal lists
Description
- A user copies a bookmark from a personal list to other personal lists.
- Since all bookmarks are always present in the All Favorites (favorites) list, copying from personal lists to this central list is not possible.
API mapping
- FA07 | Add bookmark to other lists (for every list)
- POST /favourites/folders/{folderID}/bookmarks
Model
Bookmark
Fields
Field | Data type | Description |
---|---|---|
id | String | ID of the bookmark (internal created by Elasticsearch) |
itemId | String | ID of the DDB object item |
description | String | User defined text to describe the list |
userId | String | AAS/LDAP managed ID of the User |
bookmarkType | String | Type of the bookmark |
createdAt | Long | Creation date of the folder in millis created by the DDB Backend |
updateAt | Long | Last Update date of the folder in millis created by the DDB Backend |
keywordTool | KeywordTool | Optional data for internal use in APD (for keyword tool) |
Description
- Model object to hold a bookmark (= favorites)
Remarks
- The possible types of a bookmark are:
- CULTURAL_ITEM | INSTITUTION | ENTITY | NEWSPAPER | ARTICLE
Bookmark's KeywordTool
Fields
Field | Data type | Description |
---|---|---|
Done | Boolean | Used in APD |
Description
- Model object to hold and transfer APD internal data
BookmarkResult
Fields
Field | Data type | Description |
---|---|---|
query | String | Summary of the executed query (for debugging use) |
total | Long | Total matches |
offset | Long | Used offset (default or send by the request) |
size | Long | Used size (default or send by the request) |
bookmarks | List<Bookmark> | List of the found bookmarks by the query |
Description
- Model object to hold bookmarks (depends of offset and size) by the query
Folder
Fields
Field | Data type | Description |
---|---|---|
id | String | ID of the folder (internal created by Elasticsearch) |
portal | Portal enum | Name of used portal |
title | String | Title of the user list |
description | String | User defined text to describe the list |
userId | String | AAS/LDAP managed ID of the User |
publishingName | String | User Identifier if the list is published |
createdAt | Long | Creation date of the folder in millis created by the DDB Backend |
updateAt | Long | Last Update date of the folder in millis created by the DDB Backend |
bookmarkIds | Set<String> | List of related bookmarks IDs |
institutionIds | Set<String> | List of related institution IDs |
blockingToken | String | Optional token for internal use in APD |
blocked | Boolean | If the list is blocked for public use |
published | Boolean | If the list is published for public use |
keywordTool | KeywordTool | Optional data for internal use in APD (for keyword tool) |
Description
- Model object to hold a folder (= favorites list and user defined lists)
Folder's KeywordTool
Fields
Field | Data type | Description |
---|---|---|
sentToAdmin | Boolean | Used in APD |
Description
- Model object to hold and transfer APD internal data
FolderResult
Fields
Field | Data type | Description |
---|---|---|
query | String | Summary of the executed query (for debugging use) |
total | Long | Total matches |
offset | Long | Used offset (default or send by the request) |
size | Long | Used size (default or send by the request) |
folders | List<Folder> | List of the found folders by the query |
Description
- Model object to hold found folders (depends of offset and size) by the query
Portal
Possible values
Value | Description |
---|---|
DDB | DDB Portal with CCC |
NEWSPAPER | Zeitungsportal |
Description
- Defines the portal to used for storing and loading folders and bookmarks
- Default value is DDB