API endpoints

FA01 | Create bookmark

POST	/favourites/bookmarks

Remarks

The parameter folderId folderIds 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.
folders for adding the new created bookmark.
The JSON properties itemId and (bookmark) type must exist.
In portal DDB the folderId favorites must always used.

Query parameters Query parameters

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",							// Required
	"createdAt": 1683641908448,							// Not used
	"updatedAt": 1683641908448,							// Not used
	"keywordTool": {									// Optional
		"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.

Example call(s)

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

^ Back to top

FA02 | Retrieve bookmark

...

GET

...

/favourites/bookmarks/{id}

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

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 foundcreated
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 authorized404 = Bookmark ID not found
500 = Internal server error

Related Use Case(s)

UC01 | Create bookmark
- The user selects an object from an object list as a favorite
All info of a bookmark is retrieved to display it in the frontend
- .

Example call(s)

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

^ Back to top

...

FA02 | Retrieve

...

bookmark

GET	/favourites/bookmarks/{id}

...

Response payload

...

Code Block

...

theme

...

Midnight

...

title

...

Bookmark object
linenumbers	true
collapse	true

 {
	"id": "rjzgAIgBdHmpxQQKvQHm",
	"itemId": "IVMX3IRHKU725WR2HHT6VY2AFFS72FGK",
	"description": "My important description",
	"userId": "

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": FalseTrue
			},
		},
		{
			"id": "nDxWtIgBdHmpxQQKNxNQ",
			"itemId": "IVMX3IRHKU725WR2HHT6VY2AFFS72FGK",
			"description": "Neues Lesezeichen",
			"userId": "fachstelle_museum",
			"type": "CULTURAL_ITEM",
			"createdAt": 1683641908448,
			"updatedAt": 1683641908448,
			"keywordTool": {
				"done": False
			},
		}
	]
}

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

^ Back to top

FA04 | Update bookmark

...

PUT

...

/favourites/bookmarks/{id}

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

^ Back to top

...

FA03 | Retrieve bookmarks

GET	/favourites/bookmarks

Query parameters

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
			},
		}
	]
}

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

^ 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",

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

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",						// Not used
	"type": "INSTITUTION",								// Optional
	"createdAt": 1683641908448,							// Not used
	"updatedAt": 1683641908448,							// Not used
	"keywordToolitemId": {	"IVMX3IRHKU725WR2HHT6VY2AFFS72FGK",								// Optional
		"donedescription": false
	}
}

Response payload

Code Block

theme	Midnight
title	Bookmark object
linenumbers	true
collapse	true

 {
	"id"Another description",				// Optional
	"userId": "rjzgAIgBdHmpxQQKvQHmfachstelle_museum",						// Not used
	"itemIdtype": "IVMX3IRHKU725WR2HHT6VY2AFFS72FGKINSTITUTION",
	"description": "Another description",								// Optional
	"userIdcreatedAt": "fachstelle_museum",
	"type": "INSTITUTION",1683641908448,							// Not used
	"createdAtupdatedAt": 1683641908448,
	"updatedAt": 1683641908555,							// Not used
	"keywordTool": {									// Optional
		"done": false								 	// Optional
	}
}

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": "rjzgAIgBdHmpxQQKvQHm",
	"itemId": "IVMX3IRHKU725WR2HHT6VY2AFFS72FGK",
	"description": "Another description",
	"userId": "fachstelle_museum",
	"type": "INSTITUTION",
	"createdAt": 1683641908448,
	"updatedAt": 1683641908555,
	"keywordTool": {
		"done": false
	}
}

Status codes

200 = Bookmark updated

Status codes

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

Related Use Case(s)

UC07 | Change bookmark descriptionUC06 | Delete bookmarks in All Favorites
- A user deletes changes the description of a bookmark from favorites (and the rest of the lists).

Example call(s)

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

^ Back to top

...

FA05 |

...

Delete bookmark

POST

DELETE	/favourites/foldersbookmarks/{id}

...

Response payload

Code Block

theme	Midnight
title	Folder objectResponse
linenumbers	true
collapse	true

{
	"id    "took": "73611165cc142ae53176707d5a92e8f3",	// Not used11,
    "portalerrors": "DDB",							// Requiredfalse,
    "titleresult": [
        {
            "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

Related Use Case(s)

UC06 | Delete bookmarks in All Favorites
- 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

^ Back to top

...

FA06 | Create folder

POST	/favourites/folders

Request payload

Code Block

theme	Midnight
title	Folder object
linenumbers	true
collapse	true

{
	"id": "73611165cc142ae53176707d5a92e8f3",	// Not used
    "portal": "DDB" "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 Required | Allowed values are: DDB or NEWSPAPER
    "title": true"favorites",						// Required
	"description": "Das ist ein Test!",			// Optional
	"keywordTooluserId": {"fachstelle_museum",				// Not used
	"publishingName": "xxx",					// Optional
		"sentToAdmincreatedAt": 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
	}
}

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.

Example call(s)

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

^ Back to top

FA07 | Add bookmark to folder

...

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.

Query parameters

...

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

Status codes

200 = Folder created
400 = Property title is missing or Property portal is unkown

Status codes

200 = Bookmarks added
400 = Bookmark ID not exist
401 = User is not authorized
404 409 = Folder ID not existalready exists
500 = Internal server error

Related Use Case(s)

UC05 | Add personal folder
- A user creates a personal folder
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.

Example call(s)

Add bookmark to Create folder
- POST https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/ZjxwJIsBdHmpxQQKjyxB/bookmarks?bookmarkId=ZTxuJIsBdHmpxQQKUSwX

^ Back to top

...

FA07 |

...

Add bookmark to folder

GET

POST	/favourites/folders/{idfolderId}/bookmarks

Response payload

Remarks

Only DDB portal: 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	Required
bookmarkId	ID of bookmark to add	Once	-	Yes

Response payload

Code Block

theme	Midnight
title	Response

Code Block

theme	Midnight
title	Folder object
linenumbers	true
collapse	true

{
	    "id": "73611165cc142ae53176707d5a92e8f3"
	"title": "favorites",
	"description": "Das ist ein Test!",
	"userIdTC07____________FL01",
    "index": "fachstelle_museumfolder",
	"publishingName    "statusCode": "xxx"200,
	"createdAt": 1682070216141,
	"updatedAt": 1683642142482,
	"bookmarksIds    "result": [
		"MESR_IcBosJ3rUWzhkJj",
		"rjzgAIgBdHmpxQQKvQHm"
	],
	"institutionIds": [
		"MESR_IcBosJ3rUWzhkJj"
	],
	"blockingToken": "Test",
	"blocked": true,
	"published": true,
	"keywordTool": {
		"sentToAdmin": false
	}
}

Status codes

"updated"
}

Status codes

200 = Bookmark added
400 = Bookmark ID not exist200 = Folder found
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
All info of a list is retrieved to display it in the frontend
- .

Example call(s)

Retrieve Add bookmark to folder
- GET POST https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/ZjxwJIsBdHmpxQQKjyxB/bookmarks?bookmarkId=ZTxuJIsBdHmpxQQKUSwX

^ Back to top

...

FA08 | Retrieve

...

folder

GET	/favourites/folders/{id}/bookmarks

Remarks

Endpoint could be used in 3 usage modes

Usage modes

Mode	Description	Login required
DDB	Retrieve published DDB folder	No
Newspaper	Retrieve any Newspaper folder	No
User	Retrieve user folder	Yes

Response payload

Code Block

theme	Midnight
title	BookmarkResult Folder object
linenumbers	true
collapse	true

{
	"queryid": "user:"73611165cc142ae53176707d5a92e8f3" AND folder:"p0Qyo4cBosJ3rUWznjiY""73611165cc142ae53176707d5a92e8f3"
	"portal": "DDB",
	"totaltitle": 4"favorites",
	"offsetdescription": 0"Das ist ein Test!",
	"sizeuserId": 9999"fachstelle_museum",
	"bookmarkspublishingName": [
		{"xxx",
			"idcreatedAt": "rjzgAIgBdHmpxQQKvQHm"1682070216141,
			"itemIdupdatedAt": "IVMX3IRHKU725WR2HHT6VY2AFFS72FGK"1683642142482,
			"descriptionbookmarksIds": [
		"MESR_IcBosJ3rUWzhkJj",
		"rjzgAIgBdHmpxQQKvQHm"
	],
	"userIdinstitutionIds": [
		"fachstelleMESR_museumIcBosJ3rUWzhkJj"
	],
			"typeblockingToken": "CULTURAL_ITEMTest",
			"createdAtblocked": 1683641908448true,
			"updatedAtpublished": 1683641908448true,
			"keywordTool": {
				"donesentToAdmin": Falsefalse
			},
		},
		{
			"id": "nDxWtIgBdHmpxQQKNxNQ",
			"itemId": "IVMX3IRHKU725WR2HHT6VY2AFFS72FGK",
			"description": "Neues Lesezeichen",
			"userId": "fachstelle_museum",
			"type": "CULTURAL_ITEM",
			"createdAt": 1683641908448,
			"updatedAt": 1683641908448,
			"keywordTool": {
				"done": False
			},
		}
	]
}

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.

Example call(s)

Retrieve bookmarks of folder
- GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/vJ2GGYsBYUgoK0Rzg70n/bookmarks

^ Back to top

FA10 | Retrieve folders

...

GET

...

/favourites/folders

Query parameters

...

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

^ Back to top

...

FA09 | Retrieve bookmarks of a folder

GET	/favourites/folders/{id}/bookmarks

Remarks

Endpoint could be used in 3 usage modes

Usage modes

Mode	Description	Login required
DDB	Retrieve bookmarks of published DDB folder	No
Newspaper	Retrieve bookmarks of any Newspaper folder	No
User	Retrieve bookmarks of an user folder	Yes

Response payload

Code Block

theme	Midnight
title	BookmarkResult object
linenumbers	true
collapse	true

{
	"query": "user:"73611165cc142ae53176707d5a92e8f3" AND folder:"p0Qyo4cBosJ3rUWznjiY""

Response payload

Code Block

theme	Midnight
title	FolderResult object
linenumbers	true
collapse	true

{
	"query": "user:"73611165cc142ae53176707d5a92e8f3"",
	"total": 194,
	"offset": 0,
	"size": 9999,
	"foldersbookmarks": [
		{
			"id": "Sjszo4cBdHmpxQQKUvahrjzgAIgBdHmpxQQKvQHm",
 			"portalitemId": "DDBIVMX3IRHKU725WR2HHT6VY2AFFS72FGK",
 			"titledescription": "Schiller",
			"description": "",
			"userId": "fachstelle_museum",
			"publishingNametype": "dioCULTURAL_ITEM",
			"createdAt": 16820702623711683641908448,
			"updatedAt": 16836421427871683641908448,
			"bookmarksIdskeywordTool": ["MUSR_IcBosJ3rUWzmkLU"],
{
				"institutionIdsdone": Null,False
			},
		},
		{
			"blockingTokenid": "nDxWtIgBdHmpxQQKNxNQ",
			"keywordToolitemId": {"IVMX3IRHKU725WR2HHT6VY2AFFS72FGK",
				"sentToAdmindescription": false
			}"Neues Lesezeichen",
			"blockeduserId": false"fachstelle_museum",
			"publishedtype": true},
		{
			"id": "rjwQKYgBdHmpxQQKKgSs",
 "CULTURAL_ITEM",
			"portalcreatedAt": "DDB"1683641908448,
 			"titleupdatedAt": "favorites"1683641908448,
			"descriptionkeywordTool": "Das ist ein Test!",{
				"userIddone": "fachstelle_museum",False
			"publishingName": "xxx"},
			"createdAt": 1682070216141,
			"updatedAt": 1683642142482,
			"bookmarksIds": [],
			"institutionIds": none,
			"blockingToken": "Test",
			"keywordTool": {
				"sentToAdmin": false
			},
			"blocked": true,
			"published": true
		}
	]
}}
	]
}

Status codes

200 = Folder (s) found400 = Missing some search paramsfound
401 = User not authorized
404 = Folder not exist
500 = Internal server error

Related Use Case(s)

UC04 | Retrieve bookmarks of a listUC03 | Listennamen eines Benutzers abrufen
- The user retrieves bookmarks of a specified list.

Example call(s)

Retrieve bookmarks of 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/vJ2GGYsBYUgoK0Rzg70n/bookmarks

^ Back to top

...

FA10 |

...

Retrieve folders

POST

GET	/favourites/folders/{id}

Request payload

Code Block

theme	Midnight
title	Folder object
linenumbers	true
collapse	true

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

Response payload

folders

Remarks

Endpoint could be used in 3 usage modes

Usage modes

Mode	Description	Possible params	Login required
Institution	Search folders by a DDB institution	Only institution param used	No
Public	Search published DDB folders	Params not used	No
User	Search user folders	Any combination of userId/portal/title	Yes

Query parameters

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, for other portals required
title	Title of folder	Once	-	At least userId or title required
institution	ID of institution	Once	-	Only ID of institution
offset	Beginn offset of results	Once	0 (Solr default is used)	Optional
size	Size data of results	Once	10 (Solr default is used)	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",

Code Block

theme	Midnight
title	Folder object
linenumbers	true
collapse	true

{
	"id": "Sjszo4cBdHmpxQQKUvah",	
	"title": "favorites",
			"description": "Das ist ein Test!",
			"userId": "fachstelle_museum",
			"publishingName": "xxx",
			"createdAt": 1682070216141,
			"updatedAt": 1683642142482,
			"bookmarksIds": [
		"MESR_IcBosJ3rUWzhkJj"],
		"rjzgAIgBdHmpxQQKvQHm"
	],
	"institutionIds": [none,
		"MESR_IcBosJ3rUWzhkJj"
	],
	"blockingToken": "Test",
			"blockedkeywordTool": true,{
				"publishedsentToAdmin": truefalse
			},
			"keywordToolblocked": {true,
			"sentToAdminpublished": falsetrue
		}
	]
}

Status codes

200 = Folder updated(s) found
400 = Missing search param(s)
401 = User not authorized404 = 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.

Example call(s)

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

Example call(s)

Retrieve folders by user
- GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders?userId=fachstelle_museum&portal=NEWSPAPER
Retrieve folders by user and title
- GET
Update folder
- POST https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/wJ2JGYsBYUgoK0RzI71_?userId=fachstelle_museum&portal=DDB&title=favorites

^ Back to top

...

FA11 |

...

Update folder

DELETE

POST	/favourites/folders/{id}

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.

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

...

DELETE

...

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

Remarks

Only DDB portal: The folder favorites is protected and could not be modified.

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

Status codes

200 = Folder updated
400 = Folder favorites could not be modified (Only for DDB portal)
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.

Example call(s)

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

^ Back to top

...

FA12 | Delete folder

DELETE	/favourites/folders/{id}

Remarks

Only DDB portal: The folder favorites is protected and could not be deleted here.

Response payload

Code Block

theme	Midnight
title	Response
linenumbers	true
collapse	true

{
    "id": "TC12____________FL01",
    "index": "folder",
    "statusCode": 200,
    "result": "deleted"
}

Status codes

200 = Folder deleted
400 = Folder favourites could not be deleted (Only for DDB portal)
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.

Example call(s)

Delete folder
- DELETE https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/wJ2JGYsBYUgoK0RzI71_

^ Back to top

...

FA13 | Remove bookmark from folder

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

Remarks

The folder ID and bookmark ID must exist before deleting something.
Only for DDB portal:A bookmark could not be deleted from the main folder (favorites), because this is done only if the bookmark is deleted (see Delete Bookmark).

Response payload

Code Block

theme	Midnight
title	Response
linenumbers	true
collapse	true

{
    "id": "TC13____________FL01",
    "index": "folder",
    "statusCode": 200,
    "result": "updated"
}

Status codes

200 = Bookmark in Folder deleted
400 = Bookmark ID not found
Only for DDB portal:Folder ID of favourites is used.
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.

Example call(s)

Delete bookmarks from folder
DELETE https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/wJ2JGYsBYUgoK0RzI71_/bookmarks/vp2GGYsBYUgoK0Rzh71c

^ Back to top

...

FA14 | Delete all bookmarks and folders

DELETE	/favourites/folders

Remarks

This endpoint deletes all stored bookmarks and folders from a user for every portal.

Query parameters

Name	Value	Occurence	Default	Required
userId	ID of user to delete	Once	-	Yes

Response payload

Code Block

theme	Midnight
title	Response
linenumbers	true
collapse	true

{
    "took": 0,
    "errors": false,
    "result": [
        {
            "id": "TC14____________BM02",
            "index": "bookmark",
            "statusCode": 200,
            "result": "deleted"
        },
        {
            "id": "TC14____________BM01",
            "index": "bookmark",
            "statusCode": 200,
            "result": "deleted"
        },
        {
            "id": "TC14____________FL01",
            "index": "folder",
            "statusCode": 200,
            "result": "deleted"
        },
        {
            "id": "TC14____________FL02",
            "index": "folder",
            "statusCode": 200,
            "result": "deleted"
        },
        {
            "id": "TC14____________FL03",
            "index": "folder",
            "statusCode": 200,
            "result": "deleted"
        },
        {
            "id": "TC14____________FL04",
            "index": "folder",
            "statusCode": 200,
            "result": "deleted"
        }
    ],
    "statusCode": 200,
    "statusMessage": "All folders and bookmarks for user <jean_paul> deleted"
}

Status codes

200 = Bookmarks and Folders deleted
401 = User not authorized
404 = No folders found for given User ID
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

^ Back to top

...

FA15 | Download newspaper pages as ZIP

POST	/favourites/download

Remarks

Only valid formats are possible. If an invalid format will be used, then the request will rejected with 400 Bad Request.

Request payload

Code Block

theme	Midnight
title	DownloadRequest object
linenumbers	true
collapse	true

{
    "bookmarkIds": [
        "TC15____________BM01",
        "TC15____________BM02",
        "TC15____________BM03",
        "TC15____________BM04",
        "TC15____________BM05",
        "TC15____________BM06"
    ],
    "formats": [
        "TXT", "CSV", "ALTO", "IMAGE"     
	]
}

Response payload

ZIP file with requested formats:
ALTO: Delivers ALTO files for every selected newspaper
IMAGE: Delivers images for every selected newspaper
TXT: Delivers text files with fulltext for every selected newspaper page
CSV: Delivers one CSV summary for all pages

Status codes

200 = ZIP successfully created and delivered
400 = No valid bookmark id found (invalid IDs will be skipped)
401 = User not authorized
500 = Internal server error

Example call(s)

Download ZIP
POST

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.

Example call(s)

Delete bookmarks from folder
DELETE https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/wJ2JGYsBYUgoK0RzI71_/bookmarks/vp2GGYsBYUgoK0Rzh71c

^ Back to top

FA14 | Delete all bookmarks and folders

...

DELETE

...

/favourites/folders

Query parameters

...

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_museumdownload

^ Back to top

...

API calls for Use Cases

...

Model object to hold a bookmark (= favorites)

Remarks

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

...

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)

...

Model object to hold found folders (depends of offset and size) by the query

^ Back to top

...

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

^ Back to top

...

Page tree

Page History

Versions Compared

Old Version 47

New Version Current

Key

API endpoints

FA01 | Create bookmark

Remarks

Query parameters Query parameters

Request payload

Status codes

Related Use Case(s)

Example call(s)

FA02 | Retrieve bookmark

Response payload

Response payload

Status codes

Related Use Case(s)

Example call(s)

FA02 | Retrieve

bookmark

Response payload

Response payload

Status codes

Related Use Case(s)

Example call(s)

FA04 | Update bookmark

Status codes

Related Use Case(s)

Example call(s)

FA03 | Retrieve bookmarks

Query parameters

Response payload

Status codes

Related Use Case(s)

Example call(s)

FA04 | Update bookmark

Request payload

Remarks

Request payload

Response payload

Status codes

Related Use Case(s)

Example call(s)

FA05 | Delete bookmark

Response payload

Status codes

Status codes

Related Use Case(s)

Example call(s)

FA05 |

Delete bookmark

Response payload

Status codes

Related Use Case(s)

Example call(s)

FA06 | Create folder

Request payload

Response payload

Status codes

Related Use Case(s)

Example call(s)

FA07 | Add bookmark to folder

Remarks

Query parameters

Response payload

Status codes

Status codes

Related Use Case(s)

Example call(s)

FA07 |

Add bookmark to folder

Response payload

Remarks

Query parameters

Response payload

Status codes

Status codes

Related Use Case(s)