...

Response payload

 {
	"id": "rjzgAIgBdHmpxQQKvQHm",
	"itemId": "IVMX3IRHKU725WR2HHT6VY2AFFS72FGK",
	"description": "My important description",
	"userId": "fachstelle_museum",
	"type": "CULTURAL_ITEM",
	"createdAt": 1683641908448,
	"updatedAt": 1683641908448,
	"keywordTool": {
		"done": True
	}
}

...

• Create bookmark only in main folder
  • GET POST https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/bookmarks
• Create bookmark in main folder and two additional folders
  • GET POST https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/bookmarks?folderIds=Sjszo4cBdHmpxQQKUvah&folderIds=rjwQKYgBdHmpxQQKKgSs

...

• 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

^ Back to top

...

FA03 | Retrieve bookmarks

...

Response payload

{
	"query": "user:"73611165cc142ae53176707d5a92e8f3",
	"total": 4,
	"offset": 0,
	"size": 9999,
	"bookmarks": [
		{
			"id": "rjzgAIgBdHmpxQQKvQHm",
			"itemId": "IVMX3IRHKU725WR2HHT6VY2AFFS72FGK",
			"description": "",
			"userId": "fachstelle_museum",
			"type": "CULTURAL_ITEM",
			"createdAt": 1683641908448,
			"updatedAt": 1683641908448,
			"keywordTool": {
				"done": False
			},
		},
		{
			"id": "nDxWtIgBdHmpxQQKNxNQ",
			"itemId": "IVMX3IRHKU725WR2HHT6VY2AFFS72FGK",
			"description": "Neues Lesezeichen",
			"userId": "fachstelle_museum",
			"type": "CULTURAL_ITEM",
			"createdAt": 1683641908448,
			"updatedAt": 1683641908448,
			"keywordTool": {
				"done": False
			},
		}
	]
}

...

• 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

^ Back ^ Back to top

...

FA04 | Update bookmark

...

• 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

...

Request payload

{
	"id": "rjzgAIgBdHmpxQQKvQHm",						// Not used
	"itemId": "IVMX3IRHKU725WR2HHT6VY2AFFS72FGK",		// Not used
	"description": "Another description",				// Optional
	"userId": "fachstelle_museum",						// Not used
	"type": "INSTITUTION",								// Optional
	"createdAt": 1683641908448,							// Not used
	"updatedAt": 1683641908448,							// Not used
	"keywordTool": {									// Optional
		"done": false
	}
}

...

• UC07 | Change bookmark description
  • A user changes the description of a bookmark.changes the description of a bookmark.
    

Example call(s)

• Update bookmark
  • PUT https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/bookmarks/YzxuJIsBdHmpxQQKPSya

^ Back to top

...

FA05 | Delete bookmark

/favourites/bookmarks/{id}

User permission required

Query parameters

...

...

Status codes

• 200 = Bookmark deleted
• 401 = User is not authorized
• 404 = Bookmark ID not found
• 500 = Internal server error

...

• UC06 | Delete bookmarks in All Favorites
  • A user deletes a bookmark from favorites (and the rest of the lists).lists).
    

Example call(s)

• Delete bookmark
  • DELETE https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/bookmarks/ZTxuJIsBdHmpxQQKUSwX

^ Back to top

...

FA06 | Create folder

...

• UC05 | Add personal folder
  • A user creates a personal folder.
    

Example call(s)

• Create folder
  • POST https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders

^ Back to top

...

FA07 | Add bookmark to folder

...

• 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

...

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

^ Back to top

...

FA08 | Retrieve folder

...

• 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

^ Back to top

...

FA09 | Retrieve bookmarks of a folder

...

Related Use Case(s)

• UC04 | Retrieve bookmarks of a listbookmarks of a 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
  • The user retrieves bookmarks of a specified list.

^ Back to top

...

FA10 | Retrieve folders

/favourites/folders

User permission required

Query parameters

...

• UC03 | Listennamen eines Benutzers abrufen
  • The user retrieves bookmarks of a specified list.a specified list.
    

Example call(s)

• Retrieve folder by user
  • GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders?userId=fachstelle_museum
• Retrieve folder by user and title
  • GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders?userId=fachstelle_museum&title=favorites

^ Back to top

...

FA11 | Update folder

/favourites/folders/{id}

User permission required

Query parameters

...

...

Request payload

 {
	"id": "Sjszo4cBdHmpxQQKUvah",			// Not used
	"title": "favorites",					// Optional
	"description": "Das ist ein Test!",		// Optional
	"userId": "fachstelle_museum",			// Not used
	"publishingName": "xxx",				// Optional
	"createdAt": 1682070216141,				// Not used
	"updatedAt": 1683642142482,				// Not used
	"bookmarksIds": [						// Optional
		"MESR_IcBosJ3rUWzhkJj",
		"rjzgAIgBdHmpxQQKvQHm"
	],
	"institutionIds": [						// Optional
		"MESR_IcBosJ3rUWzhkJj"
	],
	"blockingToken": "Test",				// Optional
	"blocked": true,						// Optional
	"published": true,						// Optional
	"keywordTool": {						// Optional
		"sentToAdmin": false
	}
}

...

• 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.personal list.
    

Example call(s)

• Update folder
  • POST https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/wJ2JGYsBYUgoK0RzI71_

^ Back to top

...

FA12 | Delete folder

/favourites/folders/{id}

User permission required

Query parameters

...

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

...

• UC11 | Remove personal list with 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_

^ Back to top

...

FA13 | Delete bookmark from folder

...

Related Use Case(s)

• FA13 | Delete bookmark from listDelete bookmark from list
  • A bookmark is removed from a personal list.
    

Example call(s)

• Delete bookmarks from folder
  • GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/wJ2JGYsBYUgoK0RzI71_/bookmarks/vp2GGYsBYUgoK0Rzh71c
  • A bookmark is removed from a personal list.

^ Back to top

...

FA14 | Delete all bookmarks and folders

/favourites/folders

User permission required

Query parameters

...

• 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

^ Back to top

...

API calls for Use Cases

...