API endpoints

SS01 | Store search

POST

/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

SavedSearch JSON object 
{
    "title": "Goethe",
    "type": "newspaper",
    "searchQuery": "aHR0cHM6Ly93aWtpLmRldXRzY2hlLWRpZ2l0YWxlLWJpYmxpb3RoZWsuZGUv"
}

Response payload

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

Status codes

  • 201 = Search stored
  • 400 = Title, type or queryString is missing (required)
  • 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

GET

/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

NameValueOccurenceDefaultRequired
titleTitle of searchOnce-Optional
queryStringBase 64 coded search stringOnce-Optional
typeType of search like item, entity, institution or newspaperOnce-Optional

Response payload

SavedSearch JSON object 
[
    {
        "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 = Search(es) found
  • 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 queryString
    • 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

PUT

/savedsearches/{id}

User permission required

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.

SavedSearch JSON object 
{
    "title": "Goethe",
    "type": "newspaper",
    "searchQuery": "aHR0cHM6Ly93aWtpLmRldXRzY2hlLWRpZ2l0YWxlLWJpYmxpb3RoZWsuZGUv"
}

Supported Content Type(s)

  • application/json

Status codes

  • 204 = Search updated
  • 400 = Wrong usage of endpoint
  • 401 = User is not authorized
  • 403 = Forbidden (User is not owner of Search)
  • 404 = 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

DELETE

/savedsearches/{id}

User permission required

Supported Content Type(s)

  • application/json

Status codes

  • 204 = Search deleted (No content)
  • 400 = Wrong usage of endpoint
  • 401 = User is not authorized
  • 403 = Forbidden (User is not owner of Search)
  • 404 = 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

FieldData typeDescription

id

Long

ID of the Saved Search (internal created by PostgreSQL)

title

String

User defined title of the Saved Search

type

String

Type of the Saved Search (CULTURAL_ITEM | INSTITUTION | ENTITY | NEWSPAPER(legacy))

queryString

String

Search query string with parameters filtered and sorted alphabetically. Encoded in Base64

userId

String

AAS/LDAP managed ID of the User

createdAt

XMLGregorianCalendar

Creation date of the Saved Search created by the DDB Backend

Description

  • Model object to hold a Saved Search

^ Back to top

  • No labels