openapi: 3.0.3
info:
  title: LOD API
  version: "1.0"
  description: >-
    Linked Open Data API published by the Saxony State and University Library
    (SLUB Dresden), which serves TU Dresden. Provides bibliographic and
    authority data (resources, persons, organizations, events, topics, works,
    geo) aggregated from K10Plus/SWB, GND and Wikidata, with search, source,
    reconcile and entity-lookup endpoints. Converted faithfully from the
    publicly served Swagger 2.0 document at
    https://data.slub-dresden.de/swagger.json
servers:
  - url: https://data.slub-dresden.de
tags:
  - name: source
    description: Source data access operation
  - name: authority_search
    description: Authority Provider Identifier Search
  - name: search and access
    description: Search and Access Operations
  - name: reconcile
    description: Openrefine Reconcilation and Data Extension Operations
  - name: explorative search
    description: API endpoint to be use with the explorative search webapp
paths:
  /explore/aggregations:
    get:
      tags: [explorative search]
      summary: aggregate topAuthors, datePublished and relatedTopics around topics
      operationId: aggregateTopics
      parameters:
        - name: topics
          in: query
          required: true
          description: multiple topics to aggregate
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: contributor
          in: query
          description: use this specific contributor name as filter for the aggregation result
          schema:
            type: string
        - name: restrict
          in: query
          description: restrict all topic queries to occurrences with this restriction-topic
          schema:
            type: string
      responses:
        "200":
          description: Success
        "404":
          description: Record(s) not found
  /explore/correlations:
    get:
      tags: [explorative search]
      summary: correlate topics with their mutual occurances
      operationId: correlateTopics
      parameters:
        - name: topics
          in: query
          required: true
          description: multiple topics to correlate
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
      responses:
        "200":
          description: Success
        "404":
          description: Record(s) not found
  /explore/topicsearch:
    get:
      tags: [explorative search]
      summary: perform a simple search on the topics index
      operationId: queryTopics
      parameters:
        - name: q
          in: query
          required: true
          description: query string to search
          schema:
            type: string
        - name: size
          in: query
          description: size of the response
          schema:
            type: integer
            default: 15
        - name: fields
          in: query
          description: list of internal elasticsearch fields to query against.
          schema:
            type: array
            items:
              type: string
            default:
              - preferredName^2
              - alternateName
              - description
              - additionalType.description
              - additionalType.name
          style: form
          explode: true
      responses:
        "200":
          description: Success
        "404":
          description: Record(s) not found
  /reconcile/:
    get:
      tags: [reconcile]
      summary: OpenRefine Reconcilation Service API
      description: https://github.com/OpenRefine/OpenRefine/wiki/Reconciliation-Service-API
      operationId: getReconcile
      responses:
        "200":
          description: Success
        "400":
          description: Check your JSON
        "404":
          description: Record(s) not found
    post:
      tags: [reconcile]
      summary: OpenRefine Reconcilation Service API
      description: https://github.com/OpenRefine/OpenRefine/wiki/Reconciliation-Service-API
      operationId: postReconcile
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Success
  /reconcile/flyout/entity:
    get:
      tags: [reconcile]
      summary: Openrefine Suggest-API suggest Entry Point
      description: https://github.com/OpenRefine/OpenRefine/wiki/Suggest-API
      operationId: flyoutEntity
      parameters:
        - name: id
          in: query
          description: the identifier of the entity to render
          schema:
            type: string
      responses:
        "200":
          description: Success
        "400":
          description: Check your ID
        "404":
          description: Type not found
  /reconcile/flyout/property:
    get:
      tags: [reconcile]
      summary: Openrefine Suggest-API suggest Entry Point
      description: https://github.com/OpenRefine/OpenRefine/wiki/Suggest-API
      operationId: flyoutProperty
      parameters:
        - name: id
          in: query
          description: the identifier of the property to render
          schema:
            type: string
      responses:
        "200":
          description: Success
        "404":
          description: Type not found
  /reconcile/flyout/type:
    get:
      tags: [reconcile]
      summary: Openrefine Suggest-API suggest Entry Point
      description: https://github.com/OpenRefine/OpenRefine/wiki/Suggest-API
      operationId: flyoutType
      parameters:
        - name: id
          in: query
          description: the identifier of the type to render
          schema:
            type: string
      responses:
        "200":
          description: Success
        "400":
          description: Check your ID
        "404":
          description: Type not found
  /reconcile/properties:
    get:
      tags: [reconcile]
      summary: Openrefine Data-Extension-API
      description: https://github.com/OpenRefine/OpenRefine/wiki/Data-Extension-API
      operationId: reconcileProperties
      parameters:
        - name: queries
          in: query
          description: OpenRefine Reconcilation API Call for Multiple Queries
          schema:
            type: string
        - name: type
          in: query
          description: type string
          schema:
            type: string
        - name: limit
          in: query
          description: how many properties shall be returned
          schema:
            type: string
      responses:
        "200":
          description: Success
        "400":
          description: Check your Limit
        "404":
          description: Type not found
  /reconcile/suggest/entity:
    get:
      tags: [reconcile]
      summary: Openrefine Suggest-API suggest Entry Point
      description: https://github.com/OpenRefine/OpenRefine/wiki/Suggest-API
      operationId: suggestEntity
      parameters:
        - name: prefix
          in: query
          description: a string the user has typed
          schema:
            type: string
      responses:
        "200":
          description: Success
        "400":
          description: Check your Limit
        "404":
          description: Type not found
  /reconcile/suggest/property:
    get:
      tags: [reconcile]
      summary: Openrefine Suggest-API suggest Entry Point
      description: https://github.com/OpenRefine/OpenRefine/wiki/Suggest-API
      operationId: suggestProperty
      parameters:
        - name: prefix
          in: query
          description: a string the user has typed
          schema:
            type: string
      responses:
        "200":
          description: Success
        "400":
          description: Check your Limit
        "404":
          description: Type not found
  /reconcile/suggest/type:
    get:
      tags: [reconcile]
      summary: Openrefine Suggest-API suggest Entry Point
      description: https://github.com/OpenRefine/OpenRefine/wiki/Suggest-API
      operationId: suggestType
      parameters:
        - name: prefix
          in: query
          description: a string the user has typed
          schema:
            type: string
      responses:
        "200":
          description: Success
        "400":
          description: Check your Limit
        "404":
          description: Type not found
  /search:
    get:
      tags: [search and access]
      summary: search over all entity-indices
      operationId: searchAll
      parameters:
        - name: q
          in: query
          description: Lucene Query String Search Parameter
          schema:
            type: string
        - name: format
          in: query
          description: "set the Content-Type over this Query-Parameter. Allowed: nt, rdf, ttl, nq, jsonl, json"
          schema:
            type: string
        - name: sort
          in: query
          description: "how to sort the returned datasets. like: path_to_property:[asc|desc]"
          schema:
            type: string
        - name: size
          in: query
          description: Configure the maxmimum amount of hits to be returned
          schema:
            type: integer
        - name: from
          in: query
          description: Configure the offset from the frist result you want to fetch
          schema:
            type: integer
        - name: filter
          in: query
          description: "filter the search by a defined value in a path. e.g. path_to_property:value"
          schema:
            type: string
      responses:
        "200":
          description: Success
        "404":
          description: Record(s) not found
  /source/{source_index}/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID-String of the entity to access.
        schema:
          type: string
      - name: source_index
        in: path
        required: true
        description: "The name of the source-index to access the source-data. Allowed Values: ['kxp-de14', 'swb-aut', 'gnd_marc21']"
        schema:
          type: string
    get:
      tags: [source]
      operationId: getSourceRecord
      responses:
        "200":
          description: Success
        "404":
          description: Record(s) not found
  /{authority_provider}/{entity_type}/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: "The ID-String of the authority-identifier to access. Possible Values (examples): 208922695, 118695940, 20474817, Q1585819"
        schema:
          type: string
      - name: entity_type
        in: path
        required: true
        description: "The name of the entity-index to access. Allowed Values: ['organizations', 'persons', 'resources', 'works', 'events', 'topics', 'geo']."
        schema:
          type: string
      - name: authority_provider
        in: path
        required: true
        description: "The name of the authority-provider to access. Allowed Values: ['filmportal.de', 'swb', 'wd', 'isni', 'lc', 'orcid', 'gnd', 'viaf']."
        schema:
          type: string
    get:
      tags: [authority_search]
      summary: search for an given ID of a given authority-provider on a given entity-index
      operationId: getByAuthorityAndEntity
      parameters:
        - name: format
          in: query
          description: "set the Content-Type over this Query-Parameter. Allowed: nt, rdf, ttl, nq, jsonl, json"
          schema:
            type: string
        - name: size
          in: query
          description: Configure the maxmimum amount of hits to be returned
          schema:
            type: integer
            default: 100
        - name: from
          in: query
          description: Configure the offset from the frist result you want to fetch
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Success
        "404":
          description: Record(s) not found
  /{authority_provider}/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: "The ID-String of the authority-identifier to access. Possible Values (examples): 208922695, 118695940, 20474817, Q1585819"
        schema:
          type: string
      - name: authority_provider
        in: path
        required: true
        description: "The name of the authority-provider to access. Allowed Values: ['filmportal.de', 'swb', 'wd', 'isni', 'lc', 'orcid', 'gnd', 'viaf']."
        schema:
          type: string
    get:
      tags: [authority_search]
      summary: search for an given ID of a given authority-provider
      operationId: getByAuthority
      parameters:
        - name: format
          in: query
          description: "set the Content-Type over this Query-Parameter. Allowed: nt, rdf, ttl, nq, jsonl, json"
          schema:
            type: string
        - name: size
          in: query
          description: Configure the maxmimum amount of hits to be returned
          schema:
            type: integer
            default: 100
        - name: from
          in: query
          description: Configure the offset from the frist result you want to fetch
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Success
        "404":
          description: Record(s) not found
  /{entity_type}/search:
    parameters:
      - name: entity_type
        in: path
        required: true
        description: "The name of the entity-type to access. Allowed Values: ['organizations', 'persons', 'resources', 'works', 'events', 'topics', 'geo']."
        schema:
          type: string
    get:
      tags: [search and access]
      summary: search on one given entity-index
      operationId: searchInIndex
      parameters:
        - name: q
          in: query
          description: Lucene Query String Search Parameter
          schema:
            type: string
        - name: format
          in: query
          description: "set the Content-Type over this Query-Parameter. Allowed: nt, rdf, ttl, nq, jsonl, json"
          schema:
            type: string
        - name: size
          in: query
          description: Configure the maxmimum amount of hits to be returned
          schema:
            type: integer
            default: 100
        - name: from
          in: query
          description: Configure the offset from the frist result you want to fetch
          schema:
            type: integer
            default: 0
        - name: sort
          in: query
          description: "how to sort the returned datasets. like: path_to_property:[asc|desc]"
          schema:
            type: string
        - name: filter
          in: query
          description: "filter the search by a defined value in a path. e.g. path_to_property:value"
          schema:
            type: string
      responses:
        "200":
          description: Success
        "404":
          description: Record(s) not found
  /{entity_type}/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: "The ID-String of the record to access. Possible Values (examples): 118695940, 130909696"
        schema:
          type: string
      - name: entity_type
        in: path
        required: true
        description: "The name of the entity-type to access. Allowed Values: ['organizations', 'persons', 'resources', 'works', 'events', 'topics', 'geo']."
        schema:
          type: string
    get:
      tags: [search and access]
      summary: get a single record of an entity-index, or search for all records containing this record as an attribute via isAttr parameter
      operationId: getRecord
      parameters:
        - name: format
          in: query
          description: "set the Content-Type over this Query-Parameter. Allowed: nt, rdf, ttl, nq, jsonl, json"
          schema:
            type: string
      responses:
        "200":
          description: Success
        "404":
          description: Record(s) not found