# Language: OpenAPI YAML, Project: DatAasee, License: CC-BY, Author: Christian Himpe

openapi: "3.0.3"

info:
  title: "DatAasee API"
  description: "The DatAasee API is a JSON/REST API of the DatAasee metadata-lake to search, filter, query centralized metadata from distributed sources."
  termsOfService: "https://dataasee.uni-muenster.de"
  contact:
    name: "DatAasee Support"
    url: "https://ulbmuenster.github.io/dataasee"
  license:
    name: "CC BY 4.0"
    url: "https://creativecommons.org/licenses/by/4.0/"
  version: "v1"

servers:
  - url: "https://dataasee.uni-muenster.de:8343/api/v1"
    description: "DatAasee API Server"

components:
  securitySchemes:
    basicAuth:
      type: "http"
      scheme: "basic"
      description: "Basic authentication for POST endpoints."

tags:
  - name: "data"
    description: "The \"data\" endpoints return payload data."
  - name: "support"
    description: "The \"support\" endpoints return descriptions about the data."
  - name: "system"
    description: "The \"system\" endpoints return API information and trigger actions."

paths:

  "/api":
    get:
      operationId: "dataasee-api"
      tags:
        - "system"
      summary: "Returns API specification and schemas."
      parameters:
        - name: "params"
          in: "query"
          description: "Optional; if provided, a parameter schema for the endpoint in the parameter value is returned."
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=api"
        - name: "request"
          in: "query"
          description: "Optional; if provided, a request schema for the endpoint in the parameter value is returned."
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=api"
        - name: "response"
          in: "query"
          description: "Optional; if provided, a response schema for the endpoint in the parameter value is returned."
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=api"
      responses:
        default:
          description: "All \"api\" Responses"
          content:
            "application/json":
              schema:
                type: "object"
                externalDocs:
                  url: "/api?response=api"

  "/ready":
    get:
      operationId: "dataasee-ready"
      tags:
        - "system"
      summary: "Returns service readiness."
      responses:
        default:
          description: "All \"ready\" Responses"
          content:
            "application/json":
              schema:
                type: "object"
                externalDocs:
                  url: "/api?response=ready"

  "/schema":
    get:
      operationId: "dataasee-schema"
      tags:
        - "support"
      summary: "Returns database schema."
      parameters:
        - name: "prop"
          in: "query"
          description: "Optional; if provided only selected property is returned."
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=schema"
      responses:
        default:
          description: "All \"schema\" Responses"
          content:
            "application/json":
              schema:
                type: "object"
                externalDocs:
                  url: "/api?response=schema"

  "/metadata":
    get:
      operationId: "dataasee-metadata"
      tags:
        - "data"
      summary: "Returns metadata records."
      parameters:
        - name: "id"
          in: "query"
          description: "Optional; if provided, a metadata record with this value is returned."
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=metadata"
        - name: "source"
          in: "query"
          description: "Optional; if provided, metadata records from this source are returned."
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=metadata"
        - name: "search"
          in: "query"
          description: "Optional; if provided, full-text search results for this value are returned."
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=metadata"
        - name: "language"
          in: "query"
          description: "Optional; if provided, filter results by `language` are returned."
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=metadata"
        - name: "resourcetype"
          in: "query"
          description: "Optional; if provided, filter results by `resourceType` are returned."
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=metadata"
        - name: "license"
          in: "query"
          description: "Optional; if provided, filter results by `license` are returned."
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=metadata"
        - name: "category"
          in: "query"
          description: "Optional; if provided, filter results by `categories` are returned."
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=metadata"
        - name: "format"
          in: "query"
          description: "Optional; if provided, filter results by `rawFormat` are returned, also used to set format of single record"
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=metadata"
        - name: "doi"
          in: "query"
          description: "Optional; if provided, filter results by `identifier.data` are returned."
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=metadata"
        - name: "from"
          in: "query"
          description: "Optional; if provided, filter results greater or equal `publicationYear` are returned."
          required: false
          schema:
            type: "integer"
            externalDocs:
              url: "/api?params=metadata"
        - name: "till"
          in: "query"
          description: "Optional; if provided, filter results lesser or equal `publicationYear` are returned."
          required: false
          schema:
            type: "integer"
            externalDocs:
              url: "/api?params=metadata"
        - name: "page"
          in: "query"
          description: "Optional; if provided, the n-th page of results is returned."
          required: false
          schema:
            type: "integer"
            externalDocs:
              url: "/api?params=metadata"
        - name: "newest"
          in: "query"
          description: "Optional; if provided, results are sorted new-to-old if true, or old-to-new if false, by default, no sorting."
          required: false
          schema:
            type: "boolean"
            externalDocs:
              url: "/api?params=metadata"
      responses:
        default:
          description: "All \"metadata\" Responses"
          content:
            "application/json":
              schema:
                type: "object"
                externalDocs:
                  url: "/api?response=metadata"

  "/database":
    get:
      operationId: "dataasee-database"
      tags:
        - "data"
      summary: "Returns metadata queries."
      parameters:
        - name: "language"
          in: "query"
          description: "Optional; if provided, sets `query` language, by default SQL is assumed."
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=database"
        - name: "query"
          in: "query"
          description: "Required; the query."
          required: true
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=database"
      responses:
        default:
          description: "All \"database\" Responses"
          content:
            "application/json":
              schema:
                type: "object"
                externalDocs:
                  url: "/api?response=database"

  "/health":
    post:
      operationId: "dataasee-health"
      tags:
        - "system"
      summary: "Returns service liveness."
      security:
        - basicAuth: []
      responses:
        default:
          description: "All \"health\" Responses"
          content:
            "application/json":
              schema:
                type: "object"
                externalDocs:
                  url: "/api?response=health"

  "/ingest":
    post:
      operationId: "dataasee-ingest"
      tags:
        - "system"
      summary: "Triggers async ingest of metadata records from source."
      security:
        - basicAuth: []
      requestBody:
        description: "All Requests"
        content:
          "application/json":
            schema:
              type: "object"
              externalDocs:
                url: "/api?request=ingest"
          "application/x-www-form-urlencoded":
            schema:
              type: "object"
              externalDocs:
                url: "/api?request=ingest"
        required: true
      responses:
        default:
          description: "All \"ingest\" Responses"
          content:
            "application/json":
              schema:
                type: "object"
                externalDocs:
                  url: "/api?response=ingest"