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

openapi: "3.0.3"

info:
  title: "DatAasee API"
  description: "Public and protected API of the DatAasee metadata lake."
  termsOfService: "http://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: "http://dataasee.uni-muenster.de:8343/api/v1"
    description: "DatAasee API Server"

components:
  securitySchemes:
    basicAuth:
      type: "http"
      scheme: "basic"

tags:
  - name: "data"
  - name: "support"
  - name: "system"

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 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 Responses"
          content:
            "application/json":
              schema:
                type: "object"
                externalDocs:
                  url: "/api?response=ready"

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

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

  "/sources":
    get:
      operationId: "dataasee-sources"
      tags:
        - "support"
      summary: "Returns ingested metadata sources."
      responses:
        default:
          description: "All Responses"
          content:
            "application/json":
              schema:
                type: "object"
                externalDocs:
                  url: "/api?response=sources"

  "/stats":
    get:
      operationId: "dataasee-stats"
      tags:
        - "support"
      summary: "Returns metadata record statistics."
      responses:
        default:
          description: "All Responses"
          content:
            "application/json":
              schema:
                type: "object"
                externalDocs:
                  url: "/api?response=stats"

  "/metadata":
    get:
      operationId: "dataasee-metadata"
      tags:
        - "data"
      summary: "Returns queried 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: "query"
          in: "query"
          description: "Optional; if provided, query results using this value are returned, the query language is set by `language`."
          required: false
          schema:
            type: "string"
            externalDocs:
              url: "/api?params=metadata"
        - name: "language"
          in: "query"
          description: "Optional; if provided, filter results by `language` are returned, also used to set `query` language."
          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 `metadataFormat` 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: "string"
            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: "string"
            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: "number"
            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 Responses"
          content:
            "application/json":
              schema:
                type: "object"
                externalDocs:
                  url: "/api?response=metadata"

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

  "/health":
    post:
      operationId: "dataasee-health"
      tags:
        - "system"
      summary: "Probes and returns service liveness."
      security:
        - basicAuth: []
      responses:
        default:
          description: "All 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"
        required: true
      responses:
        default:
          description: "All Responses"
          content:
            "application/json":
              schema:
                type: "object"
                externalDocs:
                  url: "/api?response=ingest"

  "/insert":
    post:
      operationId: "dataasee-insert"
      tags:
        - "system"
      summary: "Inserts single metadata record (discouraged)."
      security:
        - basicAuth: []
      requestBody:
        description: "All Requests"
        content:
          "application/json":
            schema:
              type: "object"
              externalDocs:
                url: "/api?request=insert"
        required: true
      responses:
        default:
          description: "All Responses"
          content:
            "application/json":
              schema:
                type: "object"
                externalDocs:
                  url: "/api?response=insert"