Page History

...

Remarks

The parameter folderId folderIds defines folders to add for adding the new created bookmark.Duplicates for folderIds are not possible because of using a set.
In portal DDB the folderId favorites must always used.

...

Name	Value	Occurence	Default	Required
folderIds	ID of folder(s)	Multiple	-	Yes, at least one folderId

...

Request payload

Code Block

theme	Midnight
title	Bookmark object
linenumbers	true
collapse	true

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

Status codes

Response payload

Code Block

theme	Midnight
title	Bookmark object
linenumbers	true
collapse	true

 {
	"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)
400 = At least one folder id is missing (in portal DDB it must be at least id of folder "favorites")
200 = Bookmark created
400 = Item Id is missing (required)
400 = At least one folder id is missing (in portal DDB it must be at least id of folder "favorites")
401 = User is not authorized
500 = Internal server error

...

Example call(s)

Create bookmark in main folder and two additional foldersfolders (If DDB the favorites folder must be one of the folderIds)
- POST https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/bookmarks?folderIds=Sjszo4cBdHmpxQQKUvah&folderIds=rjwQKYgBdHmpxQQKKgSs

...

Name	Value	Occurence	Default	Required
userId	ID of user	Once	-	At least userId or one itemId required
itemIds	IDs of items	Multiple	-	At least userId or one itemId required
offset	Offset of result	Once	-1-	Optional
size	Length of result	Once	-1-	Optional

Response payload

Code Block

theme	Midnight
title	Bookmark result object
linenumbers	true
collapse	true

{
	"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)

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

FA04 | Update bookmark

...

PUT

...

/favourites/bookmarks/{id}

- 2/favourites/bookmarks?userId=fachstelle_museum&itemIds=itemId________________________01

^ Back to top

...

FA04 | Update bookmark

PUT	/favourites/bookmarks/{id}

Request payload

Code Block

theme	Midnight
title	Bookmark object
linenumbers	true
collapse	true

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

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.

...

Response

payload

Code Block

theme	Midnight
title	Bookmark object
linenumbers	true
collapse	true

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

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.

Example call(s)

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

^ Back to top

...

FA05 | Delete bookmark

DELETE	/favourites/bookmarks/{id}

Response payload

Code Block

theme	Midnight
title	Bookmark object
linenumbers	true
collapse	true

 {
	"id    "took": 11,
    "rjzgAIgBdHmpxQQKvQHmerrors": false,
	"itemId    "result": "IVMX3IRHKU725WR2HHT6VY2AFFS72FGK",
	"description": "Another description",
	"userId": "fachstelle_museum",
	"type": "INSTITUTION",
	"createdAt": 1683641908448,
	"updatedAt": 1683641908555,
	"keywordTool": {
		"done": false
	}
}

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.

Example call(s)

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

^ Back to top

FA05 | Delete bookmark

...

DELETE

...

/favourites/bookmarks/{id}

 [
        {
            "id": "TC05____________BM01",
            "index": "bookmark",
            "statusCode": 200,
            "result": "deleted"
        }
    ],
    "statusCode": 200,
    "statusMessage": null
}

Status codes

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

...

POST	/favourites/folders

Request payload

Code Block

theme	Midnight
title	Folder object
linenumbers	true
collapse	true

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

Response payload

Code Block

theme	Midnight
title	Folder object
linenumbers	true
collapse	true

 {
	"id": "73611165cc142ae53176707d5a92e8f3"
	"portal": "DDB",
	"title": "favorites",
	"description": "Das ist ein Test!",
	"userId": "fachstelle_museum",
	"publishingName": "xxx",
	"createdAt": 1682070216141,
	"updatedAt": 1683642142482,
	"bookmarksIds": [
		"MESR_IcBosJ3rUWzhkJj",
		"rjzgAIgBdHmpxQQKvQHm"
	],
	"institutionIds": [
		"MESR_IcBosJ3rUWzhkJj"
	],
	"blockingToken": "Test",
	"blocked": true,
	"published": true,
	"keywordTool": {
		"sentToAdmin": false
	}
}

...

POST	/favourites/{id}/bookmarks

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.

...

GET	/favourites/folders/{id}

Response payload

Code Block

theme	Midnight
title	Folder object
linenumbers	true
collapse	true

{
	"id": "73611165cc142ae53176707d5a92e8f3"
	"portal": "DDB",
	"title": "favorites",
	"description": "Das ist ein Test!",
	"userId": "fachstelle_museum",
	"publishingName": "xxx",
	"createdAt": 1682070216141,
	"updatedAt": 1683642142482,
	"bookmarksIds": [
		"MESR_IcBosJ3rUWzhkJj",
		"rjzgAIgBdHmpxQQKvQHm"
	],
	"institutionIds": [
		"MESR_IcBosJ3rUWzhkJj"
	],
	"blockingToken": "Test",
	"blocked": true,
	"published": true,
	"keywordTool": {
		"sentToAdmin": false
	}
}

...

GET	/favourites/folders/{id}/bookmarks

Response payload

Code Block

theme	Midnight
title	BookmarkResult object
linenumbers	true
collapse	true

{
	"query": "user:"73611165cc142ae53176707d5a92e8f3" AND folder:"p0Qyo4cBosJ3rUWznjiY"",
	"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
			},
		}
	]
}

...

Name	Value	Occurence	Default	Required
userId	ID of user	Once	-	At least userId or title required
portal	Name of used portal	Once	DDB-	Optional for DDB, else required
title	Title of folder	Once	-	At least userId or title required
offset	Beginn offset of results	Once	-1-	Optional
size	Size data of results	Once	-1-	Optional

Response payload

Code Block

theme	Midnight
title	FolderResult object
linenumbers	true
collapse	true

{
	"query": "user:"73611165cc142ae53176707d5a92e8f3"",
	"total": 19,
	"offset": 0,
	"size": 9999,
	"folders": [
		{
			"id": "Sjszo4cBdHmpxQQKUvah",
 			"portal": "DDB",
 			"title": "Schiller",
			"description": "",
			"userId": "fachstelle_museum",
			"publishingName": "dio",
			"createdAt": 1682070262371,
			"updatedAt": 1683642142787,
			"bookmarksIds": ["MUSR_IcBosJ3rUWzmkLU"],
			"institutionIds": Null,
			"blockingToken": "",
			"keywordTool": {
				"sentToAdmin": false
			},
			"blocked": false,
			"published": true},
		{
			"id": "rjwQKYgBdHmpxQQKKgSs",
 			"portal": "DDB",
 			"title": "favorites",
			"description": "Das ist ein Test!",
			"userId": "fachstelle_museum",
			"publishingName": "xxx",
			"createdAt": 1682070216141,
			"updatedAt": 1683642142482,
			"bookmarksIds": [],
			"institutionIds": none,
			"blockingToken": "Test",
			"keywordTool": {
				"sentToAdmin": false
			},
			"blocked": true,
			"published": true
		}
	]
}

...

POST	/favourites/folders/{id}

Request payload

Code Block

theme	Midnight
title	Folder object
linenumbers	true
collapse	true

 {
	"id": "Sjszo4cBdHmpxQQKUvah",			// Not used
	"portal": "DDB",                        // Required
	"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
	}
}

Response payload

Code Block

theme	Midnight
title	Folder object
linenumbers	true
collapse	true

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

...

DELETE	/favourites/folders/{id}/bookmarks/{bookmarkId}

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.

...

Model object to hold a bookmark (= favorites)

Remarks

The possible types of a bookmark are:
- CULTURAL_ITEM | INSTITUTION | ENTITY | NEWSPAPER | ARTICLE

...

Page tree

Versions Compared

Old Version 55

New Version 56

Key

Remarks

Request payload

Status codes

Response payload

Status codes

Example call(s)

Response payload

Example call(s)

Example call(s)

FA04 | Update bookmark

FA04 | Update bookmark

Request payload

Remarks

Response

payload

Status codes

Related Use Case(s)

Example call(s)

FA05 | Delete bookmark

Response payload

Status codes

Related Use Case(s)

Example call(s)

FA05 | Delete bookmark

Status codes

Request payload

Response payload

Remarks

Response payload

Response payload

Response payload

Request payload

Response payload

Remarks

Remarks