...

API endpoints

SS01 | Store search

/savedsearches

User permission required

Supported Content Type(s)

• application/json

Remarks

• The JSON properties title, type and queryString must exist.
• The queryString must be encoded with Base64.
?

Request payload

-{
    "title": "Goethe",
    "type": "newspaper",
    "searchQuery": "aHR0cHM6Ly93aWtpLmRldXRzY2hlLWRpZ2l0YWxlLWJpYmxpb3RoZWsuZGUv"
}

Response payload

{
    "id": 251,
    "userId": "fachstelle_museum",
    "title": "Goethe",
    "type": "newspaper",
    "searchQuery": "aHR0cHM6Ly93aWtpLmRldXRzY2hlLWRpZ2l0YWxlLWJpYmxpb3RoZWsuZGUv",
    "createdAt": "2025-04-11T10:25:35.310+00:00"
}

Status codes

• 200 201 = Bookmark createdSearch stored
• 400 =  Item Id Title, type or queryString 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)

• Store search
  • ?POST https://dev-ddb.fiz-karlsruhe.de/api/2/savedsearches

^ Back to top

...

SS02 | Retrieves searches

/savedsearches

User permission required

Supported Content Type(s)

• application/json

Remarks

• If no query params are set, then it returns all searches of user

Query parameters

...

[
    {
        "id": 1,
        "userId": "fachstelle_museum",
        "title": "Goethe 1",
        "type": "newspaper",
        "queryString": "aHR0cHM6Ly93aWtpLmRldXRzY2hlLWRpZ2l0YWxlLWJpYmxpb3RoZWsuZGUv",
        "createdAt": "2025-04-18T10:56:08.916+00:00"
    },{
        "id": 2,
        "userId": "fachstelle_museum",
        "title": "Goethe 2",
        "type": "newspaper",
        "queryString": "bHR0cHM6Ly93aWtpLmRldXRzY2hlLWRpZ2l0YWxlLWJpYmxpb3RoZWsuZGUv",
        "createdAt": "2025-04-18T10:57:08.916+00:00"
    } 
]

Status codes

• 200 = BookmarkSearch(ses) found
• 400 = Missing some search params
• 401 = User not authorized
• 404 = No results
• 500 = Internal server error

Example call(s)

• Retrieve all searches for user
  • GET https://dev-ddb.fiz-karlsruhe.de/api/2/savedsearches/123456
• Retrieve searches by title
  • GET https://dev-ddb.fiz-karlsruhe.de/api/2/savedsearches/123456?title=Goethe 1
• Retrieve searches by search queryqueryString
  • GET https://dev-ddb.fiz-karlsruhe.de/api/2/savedsearches/123456?queryString=aHR0cHM6Ly93aWtpLmRldXRzY2hlLWRpZ2l0YWxlLWJpYmxpb3RoZWsuZGUv
  • ?
• Retrieve searches by type
  • GET https://dev-ddb.fiz-karlsruhe.de/api/2/savedsearches/123456?type=newspaper
• Retrieve searches by type, queryString and type
  • GET https://dev-ddb.fiz-karlsruhe.de/api/2/savedsearches/123456?title=Goethe 1&type=newspaper&queryString=aHR0cHM6Ly93aWtpLmRldXRzY2hlLWRpZ2l0YWxlLWJpYmxpb3RoZWsuZGUv

^ Back to top

...

SS03 | Update search

/savedsearches/{id}

User permission required

Request payload

-

Supported Content Type(s)

• application/json

Remarks

• Only JSON properties title, type and queryString could be updated.
• If JSON properties are null or not present, they are not updated and existing values are kept.
  Example: If you only set title, only the title property is updated.
• The queryString must be encoded with Base64.

Request payload

This is the Payload when every possible property should updated. Unchanged properties could be omitted.

...

{
    "title": "Goethe",
    "type": "newspaper",
    "searchQuery": "aHR0cHM6Ly93aWtpLmRldXRzY2hlLWRpZ2l0YWxlLWJpYmxpb3RoZWsuZGUv"
}

Supported Content Type(s)

• application/json

Status codes

• 200 204 = Bookmark Search updated
• 400 = Wrong usage of endpoint
• 401 = User is not authorized
• 403 = Forbidden (User is not owner of Search)
• 404 = Bookmark Search ID not found
• 500 = Internal server error

Example call(s)

• Update search
  • ?PUT https://dev-ddb.fiz-karlsruhe.de/api/2/savedsearches/123456

^ Back to top

...

SS04 | Delete search

/savedsearches/{id}

User permission required

Response payload

-

Supported Content Type(s)

• application/json

Status codes

• 200 204 = Bookmark deletedSearch deleted (No content)
• 400 = Wrong usage of endpoint
• 401 = User is not authorized
• 403 = Forbidden (User is not owner of Search)
• 404 = Bookmark Search ID not found
• 500 = Internal server error

Example call(s)

• Delete search
  ?
  • DELETE https://dev-ddb.fiz-karlsruhe.de/api/2/savedsearches/123456

^ Back to top

...

Model

SavedSearch

Fields

Description

• Model object to hold a Saved Search

^ Back to top

...