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

Remarks

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

Query parameters

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

Response payload

[
    {
        "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

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.

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