API endpoints

SS01 | Store search

POST	/savedsearches

User permission required

Remarks

The JSON properties title, type and queryString must exist.

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

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

Query parameters

Name	Value	Occurence	Default	Required
title	Title of search	Once	-	Optional
query	Base 64 coded search string	Once	-	Optional
type	Type of search like item, entity, institution or newspaper	Once	-	Optional

Response payload

Status codes

200 = Search(es) found
400 = Missing some search params
401 = User not authorized
500 = Internal server error

Example call(s)

Retrieve searches by title
- ?
Retrieve searches by search query
- ?
Retrieve searches by type
- ?

^ Back to top

SS03 | Update search

PUT	/savedsearches/{id}

User permission required

Remarks

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

Request payload

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

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

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

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