API endpoints

FA01 | Create bookmark

POST	/favourites/bookmarks

...

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

GET	/favourites/bookmarks/{id}

...

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

^ Back to top

...

FA03 | Retrieve bookmarks

...

GET	/favourites/bookmarks

...

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}

...

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

^ Back to top

...

FA05 | Delete bookmark

DELETE	/favourites/bookmarks/{id}

...

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

^ Back to top

...

FA06 | Create folder

POST	/favourites/folders

...

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

^ Back to top

...

FA07 | Add bookmark to folder

POST	/favourites/folders/{folderId}/bookmarks

...

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

GET	/favourites/folders/{id}

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

...

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

Response payload

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"

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

...

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

Remarks

Endpoint could be used in 3 usage modes

Usage modes

for of an institution in DDB for public

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

...

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

POST	/favourites/folders/{id}

Remarks

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

...

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.

...

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

...

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.

...

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.

...

Download ZIP
POST https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/download

^ Back to top

FA16 | Retrieve public folders

...

GET

...

/favourites/folders/public

Remarks

This endpoint needs no authentificated user.
The query only searches for folders with given institution id.

Query parameters

...

Response payload

Code Block

theme	Midnight
title	FolderResult object
linenumbers	true
collapse	true

{
	"query": "institution:"*"",
	"total": 2,
	"offset": 0,
	"size": 9999,
	"folders": [
		{
			"id": "Sjszo4cBdHmpxQQKUvah",
 			"portal": "NEWSPAPER",
 			"title": "Schiller 1",
			"description": "",
			"userId": "af43fc5bfa951c88e8e4b4574b39a65a",
			"publishingName": "hosc",
			"createdAt": 1682070262371,
			"updatedAt": 1683642142787,
			"bookmarksIds": ["MUSR_IcBosJ3rUWzmkLU"],
			"institutionIds": ["SV27RQJTWNOLJTNSG3ASNZSGNHBITQI2"],
			"blockingToken": "",
			"keywordTool": {
				"sentToAdmin": false
			},
			"blocked": false,
			"published": true
		},
		{
			"id": "rjwQKYgBdHmpxQQKKgSs",
 			"portal": "NEWSPAPER",
 			"title": "Schiller 2",
			"description": "",
			"userId": "af43fc5bfa951c88e8e4b4574b39a65a",
			"publishingName": "hosc",
			"createdAt": 1682070216141,
			"updatedAt": 1683642142482,
			"bookmarksIds": [],
			"institutionIds": ["SV27RQJTWNOLJTNSG3ASNZSGNHBITQI2"],
			"blockingToken": "",
			"keywordTool": {
				"sentToAdmin": false
			},
			"blocked": true,
			"published": true
		}
	]
}

Status codes

200 = Folder(s) found
400 = Missing search param(s)
500 = Internal server error

Example call(s)

Retrieve public folders
GET https://dev-ddb.fiz-karlsruhe.de/api/2/favourites/folders/public

^ 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

...

Page tree

Page History

Versions Compared

Old Version 81

New Version Current

Key

API endpoints

FA01 | Create bookmark

FA02 | Retrieve bookmark

FA03 | Retrieve bookmarks

FA04 | Update bookmark

FA05 | Delete bookmark

FA06 | Create folder

FA07 | Add bookmark to folder

FA08 | Retrieve folder

Remarks

Usage modes

Response payload

FA09 | Retrieve bookmarks of a folder

Response payload

Remarks

Usage modes

Response payload

FA10 | Retrieve folders

Remarks

Usage modes

Query parameters

FA11 | Update folder

Remarks

FA12 | Delete folder

Remarks

FA13 | Remove bookmark from folder

Remarks

FA14 | Delete all bookmarks and folders

Remarks

FA15 | Download newspaper pages as ZIP

Remarks

FA16 | Retrieve public folders

Remarks

Query parameters

Response payload

Status codes

Example call(s)

API calls for Use Cases

Remarks