You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 25 Next »

API endpoints

SS01 | Store search

POST

/savedsearches

User permission required

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

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

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

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

  • No labels