# 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: "http://dataasee.uni-muenster.de"
  license:
    name: "MIT License"
    url: "https://spdx.org/licenses/MIT.html"
  version: "v1"

servers:
  - url: "http://dataasee.uni-muenster.de:8343/api/v1"
    description: "Production Server"

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

tags:
  - name: "system"
  - name: "metadata"
  - name: "data"

paths:

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

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

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

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

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

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

  "/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:
            externalDocs:
              url: "/api?params=metadata"
        - name: "source"
          in: "query"
          description: "Optional; if provided, metadata records from this source is returned."
          required: false
          schema:
            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:
            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:
            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:
            externalDocs:
              url: "/api?params=metadata"
        - name: "resourcetype"
          in: "query"
          description: "Optional; if provided, filter results by `resourceType` are returned."
          required: false
          schema:
            externalDocs:
              url: "/api?params=metadata"
        - name: "license"
          in: "query"
          description: "Optional; if provided, filter results by `license` are returned."
          required: false
          schema:
            externalDocs:
              url: "/api?params=metadata"
        - name: "category"
          in: "query"
          description: "Optional; if provided, filter results by `categories` are returned."
          required: false
          schema:
            externalDocs:
              url: "/api?params=metadata"
        - name: "format"
          in: "query"
          description: "Optional; if provided, filter results by `metadataFormat` are returned."
          required: false
          schema:
            externalDocs:
              url: "/api?params=metadata"
        - name: "from"
          in: "query"
          description: "Optional; if provided, filter results greater or equal `publicationYear` are returned."
          required: false
          schema:
            externalDocs:
              url: "/api?params=metadata"
        - name: "till"
          in: "query"
          description: "Optional; if provided, filter results lesser or equal `publicationYear` are returned."
          required: false
          schema:
            externalDocs:
              url: "/api?params=metadata"
        - name: "page"
          in: "query"
          description: "Optional; if provided, the n-th page of results is returned."
          required: false
          schema:
            externalDocs:
              url: "/api?params=metadata"
        - name: "newest"
          in: "query"
          description: "Optional; if provided, results are sorted new-to-oldest if true (default), or old-to-new if false."
          required: false
          schema:
            externalDocs:
              url: "/api?params=metadata"
      responses:
        default:
          description: "All Responses"
          content:
            "application/json":
              schema:
                externalDocs:
                  url: "/api?response=metadata"

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

  "/ingest":
    post:
      operationId: "dataasee-ingest"
      tags:
        - "system"
      summary: "Triggers ingest from metadata source."
      security:
        - basicAuth: []
      requestBody:
        content:
          "application/json":
            schema:
              externalDocs:
                url: "/api?request=ingest"
        required: true
      responses:
        default:
          description: "All Responses"
          content:
            "application/json":
              schema:
                externalDocs:
                  url: "/api?response=ingest"

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

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