Versions Compared

Old Version 84

changes.mady.by.user Dierk Ohler

Saved on

compared with

New Version Current

changes.mady.by.user Dierk Ohler

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

API endpoints

FA01 | Create bookmark

POST

/favourites/bookmarks

User permission required

...

  • 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

User permission required

...

  • 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

User permission required

...

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

Free access to published DDB folders and all NEWSPAPER folders

(warning) Login required for user folders

...

  • Endpoint could be used in 3 usage modes

Usage modes

ModeDescriptionLogin required
DDBRetrieve published DDB folderNo
NewspaperRetrieve any Newspaper folderNo
UserRetrieve user folderYes

Response payload

Code Block
themeMidnight
titleFolder object
linenumberstrue
collapsetrue
{
	"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

...

  • Endpoint could be used in 3 usage modes

Usage modes

ModeDescriptionLogin required
DDBRetrieve bookmarks of published DDB folderNo
NewspaperRetrieve bookmarks of any Newspaper folderNo
UserRetrieve bookmarks of an user folderYes

Response payload

Code Block
themeMidnight
titleBookmarkResult object
linenumberstrue
collapsetrue
{
	"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

Free access to published DDB folders and all NEWSPAPER folders

(warning) Login required for user folders

...

  • Endpoint could be used in 3 usage modes

Usage modes

ModeDescriptionPossible paramsLogin required
InstitutionSearch folders by a DDB institution

Only institution param used

No
PublicSearch published DDB foldersParams not usedNo
UserSearch user foldersAny combination of userId/portal/titleYes

Query parameters

NameValueOccurenceDefaultRequired
userIdID of userOnce-At least userId or title required
portalName of used portalOnceDDBOptional for DDB, for other portals required
titleTitle of folderOnce-At least userId or title required
institutionID of institutionOnce-Only ID of institution
offsetBeginn offset of resultsOnce0 (Solr default is used)Optional
sizeSize data of resultsOnce10 (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}

User permission required

...

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


^ Back to top

...

FA12 | Delete folder

DELETE

/favourites/folders/{id}

User permission required

...

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

...

  • 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

User permission required

...

  • 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

...

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

^ Back to top

FA16 | Retrieve public folders (Deprecated)

...

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
themeMidnight
titleFolderResult object
linenumberstrue
collapsetrue
{
	"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

...