API endpoints

FA01 | Create bookmark

/favourites/bookmarks

User permission required

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

Response payload

Returns Bookmark JSON object:

Request payload

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

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

...

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

Response payload

Returns Bookmark JSON object:

...

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

...

• UC01 | Create bookmark
  • The user selects an object from an object list as a favorite.
    

Example call(s)

• Create bookmark in two folders (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

^ Back to top

...

FA02 | Retrieve bookmark

/favourites/bookmarks/{id}

User permission required

...

Response payload

...

...

...

...

...

Response payload

Returns BookmarkResult 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 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

/favourites/bookmarks

User permission required

Query parameters

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

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

...

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.

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

...

Request payload

Returns Bookmark JSON object:

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

Response payload

Returns Bookmark JSON object:

{
	"id": "rjzgAIgBdHmpxQQKvQHm",
	"itemId": "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.
    

FA05 | Delete bookmark

/favourites/bookmarks/{id}

User permission required

Request payload

...

...

...

...

...

...

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

FA06 | Create folder

...

POST

...

/favourites/folders

User permission required

Request payload

Returns Folder JSON object:

...

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

...

}
}

Response payload

 {
	"id": "

...

rjzgAIgBdHmpxQQKvQHm",

...

	"

...

itemId": 

...

"IVMX3IRHKU725WR2HHT6VY2AFFS72FGK",
	"

...

description": "Another 

...

description",
	"

...

userId": 

...

"fachstelle_museum",
	

...

"

...

type": 

...

Response payload

Returns Folder JSON object:

...

"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

/favourites/bookmarks/{id}

User permission required

Response payload

{
    "took": 11,
    "errors": false,
    "result": [
        {
            "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

...

Status codes

• 200 = Folder created
• 400 = Title attribute is missing
• 401 = User is not authorized
• 409 = Folder already exists
• 500 = Internal server error

Related Use Case(s)

• UC06 | Delete bookmarks in All FavoritesUC05 | Add personal folder
  • A user creates a personal folder.
    

...

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

/favourites/

folders

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

...

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.
    

FA08 | Retrieve folder

...

GET

...

/favourites/folders/{id}

User permission required

Response payload

Returns Folder JSON object:

...

Request payload

{
	"id": "73611165cc142ae53176707d5a92e8f3",	// Not used
    "portal": "DDB",							// Required | Allowed values are: DDB or NEWSPAPER
    "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
	}
}

...

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.

FA09 | Retrieve bookmarks of a folder

...

GET

...

/favourites/folders/{id}/bookmarks

User permission required

Response payload

Returns BookmarkResult JSON object:

...

Response payload

 {
	"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 foundcreated
• 401 = User not authorized
• 400 = Property title is missing or Property portal is unkown
• 401 = User is not authorized
• 409 = Folder already exists404 = 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.
    

FA10 | Retrieve folders

...

GET

...

/favourites/folders

User permission required

Query parameters

...

Response payload

Returns FolderResult JSON object:

...

• 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

/favourites/folders/{folderId}/bookmarks

User permission required

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

Response payload

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

Status codes

• 200 = Bookmark 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.
    

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

/favourites/folders/{id}

Free access to published DDB folders and all NEWSPAPER folders

Login required for user folders

Remarks

• Endpoint could be used in 3 usage modes

Usage modes

Response payload

{
	"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 (s) found400 = Missing some search params
• 401 = User is not authorized
• 404 = Folder not exist
• 500 = Internal server error

Related Use Case(s)

• UC03 | Listennamen eines Benutzers abrufenThe user retrieves bookmarks All info of a specified list.
  

FA11 | Update folder

...

POST

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

...

User permission required

Query parameters

...

Request payload

Returns Folder JSON object:

...

• • ZjxwJIsBdHmpxQQKjyxB

^ Back to top

...

FA09 | Retrieve bookmarks of a folder

/favourites/folders/{id}/bookmarks

Free access to published DDB folders and all NEWSPAPER folders

Login required for user folders

Remarks

• Endpoint could be used in 3 usage modes

Usage modes

Response payload

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

...

	]
}

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

/favourites/folders

Free access to published DDB folders and all NEWSPAPER folders

Login required for user folders

Remarks

• Endpoint could be used in 3 usage modes

Usage modes

Response payload

Returns Folder JSON object:

{
	"id": "Sjszo4cBdHmpxQQKUvah",	
	"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
• 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.
    

FA12 | Delete folder

...

DELETE

...

/favourites/folders/{id}

...

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

Related Use Case(s)

• UC11 | Remove personal list with bookmarks
  • The user deletes a personal list with the contained bookmarks.
    

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.
    

FA14 | Delete all bookmarks and folders

...

DELETE

...

/favourites/folders

User permission required

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)

...

Response payload

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

Status codes

• 200 = Folder(s) found
• 400 = Missing search param(s)
• 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.
    

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 https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders?userId=fachstelle_museum&portal=DDB&title=favorites

^ Back to top

...

FA11 | Update folder

/favourites/folders/{id}

User permission required

Remarks

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

Request payload

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

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

/favourites/folders/{id}

User permission required

Remarks

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

Response payload

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

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

User permission required

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

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

/favourites/folders

User permission required

Remarks

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

Query parameters

Response payload

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

/favourites/download

User permission required

Remarks

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

Request payload

{
    "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 https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/download

^ Back to top

...

API calls for Use Cases

UC01 | Add bookmark

...

• FA01 | Create bookmark
  • POST /favourites/bookmarks
    • Send Bookmark-JSON in body

^ Back to top

...

UC02 | Assign bookmarks to selected lists

...

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

^ Back to top

...

UC03 | Retrieve names of a user listDescription

...

• FA10 | Get all folders of a user
  • GET /favourites/folders?userId={userID}

^ Back to top

...

UC04 | Retrieve bookmarks of a list

...

• FA09 | Retrieve bookmarks of a list
  • GET /favourites/folders/{folderID}/bookmarks

^ Back to top

...

UC05 | Add personal list

Description

...

• FA06 | Create list
  • POST /favourites/folders
    • Send Folder-JSON in body

^ Back to top

...

UC06 | Delete bookmark

Description

...

• FA05 | Delete bookmark
  • DELETE /favourites/bookmarks/{bookmarkID}

^ Back to top

...

UC07 | Change bookmark description

...

• FA04 | Update bookmark (set only changes)
  • PUT /favourites/bookmarks/{bookmarkID}
    • Send Bookmark-JSON in body

^ Back to top

...

UC08 | Copy bookmarks from All Favorites to personal lists

...

• FA07 | Add bookmark to another lists
  • POST /favourites/folders/{folderID}/bookmarks?bookmarkId={bookmarkID}

^ Back to top

...

UC09 | Publish or privatize personal list

...

• FA08 | Get list with properties
  • GET /favourites/folders/{folderID}
• FA11 | Update list (set only changes)
  • POST /favourites/folders/{folderID}
    • Send Folder-JSON in body

^ Back to top

...

UC10 | Change properties of personal list

...

• FA08 | Get list
  • GET /favourites/folders/{folderID}
• FA11 | Update list (set only changes)
  • POST /favourites/folders/{folderID}
    • Send Folder-JSON in body

^ Back to top

...

UC11 | Remove personal list with bookmarks

...

• FA12 | Delete list
  • DELETE /favourites/folders/{folderID}

^ Back to top

...

UC12 | Remove personal list and contained bookmarks in all lists

...

• FA12 | Delete list
  • DELETE /favourites/folders/{folderID}

^ Back to top

...

UC13 | Remove bookmark in personal list

...

• FA13 | Remove bookmark from list
  • DELETE /favourites/folders/{folderID}/bookmarks/{bookmarkID}

^ Back to top

...

UC14 | Copy bookmarks to other personal lists

...

• FA07 | Add bookmark to other lists (for every list)
  • POST /favourites/folders/{folderID}/bookmarksbookmarks

^ Back to top

...

Model

Bookmark

Fields

...

• Model object to hold a bookmark (= favorites)

Remarks

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

^ Back to top

...

Bookmark's KeywordTool

Fields

Description

• Model object to hold and transfer APD internal data

^ Back to top

...

BookmarkResult

Fields

Description

• Model object to hold bookmarks (depends of offset and size) by the query

^ Back to top

...

Folder

Fields

Description

• Model object to hold a folder (= favorites list and user defined lists)

^ Back to top

...

Folder's KeywordTool

Fields

Description

• Model object to hold and transfer APD internal data

^ Back to top

...

FolderResult

Fields

Description

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

^ Back to top

...

Portal

Possible values

Description

• Defines the portal to used for storing and loading folders and bookmarks
• Default value is DDB

^ Back to top

...