openapi.yaml

openapi: 3.0.2
info:
  title: Lucinda server
  version: "3.2.1"

servers:
  - url: http://localhost:9997/lucinda/3.0
paths:
  /:
    get:
      description: Test if the server is working
      responses:
        200:
          description: The server is alive
          content:
            text/plain:
              schema:
                type: string
  /get/{id}:
    get:
      description: retrieve the document with the given id
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string

      responses:
        200:
          description: The requested document in binary form
          content:
            application/octet-stream:
              schema:
                type: string
                format: byte
        404:
          description: The requested document was not found

  /getmeta/{id}:
    get:
      description: retrieve the metadata of the document with the given id
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Ok, body contains the metadata
          content:
            application/json:
              schema:
                type: object
        404:
          description: The document with theb given id was not found
  /query/{expression}:
    get:
      description: Query the database with a lucene query expression as path parameter
      parameters:
        - name: querystring
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: ok, body contains a list (wich might be empty)
          content:
            application/json:
              schema:
                type: array

        400:
          description: Bad query expression
    post:
      description: Query the database with a Solr JSON expression
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#components/schemas/jsonQuery"
      responses:
        200:
          description: ok. Result is in the body
          content:
            application/json:
              schema:
                $ref: "#components/schemas/solrResponse"
        400:
          description: Bad query object

  /addfile:
    post:
      description: Indexes and immports a new document
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#components/schemas/newFile"
      responses:
        202:
          description: The new entry has been accepted and is scheduled for storage and indexing
        400:
          description: There was an error in the request
        401:
          description: This client is not allowed to create content

  /addindex:
    post:
      description: Indexes a JSON document. If a field 'contents' is provided, this field will only be indexed but not stored.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#components/schemas/newDocument"
      responses:
        201:
          description: The document was imported.
        400:
          description: There was an error with the request
        401:
          description: This client is not allowed to create content
  /listfiles:
    post:
      description: list contents of a subdirectory of the filebase
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - subdir
              properties:
                subdir:
                  type: string
                options:
                  type: object
                  properties:
                    withSubdirs:
                      type: boolean
                    withPattern:
                      type: string
      responses:
        200:
          description: ok
  /removeindex/{id}:
    get:
      description: remove the document with the given ID from the index (not from the file system!)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        204:
          description: The document was removed from the index or the document didn't exist.
        403:
          description: Removal not allowed
        404:
          description: No document with that index was found
  /rescan:
    get:
      description: initiate a rescan of the document base
      responses:
        200:
          description: Ok
  /parse:
    post:
      summary: Parse a binary file and extract its text contents.
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error

components:
  schemas:
    newDocument:
      type: object
      required:
        - filename
      properties:
        id:
          description:
            If you provide an id, that will be used. If not, an id is created automnatically.
            If you send an existing id, the previous entry with that id will be overwritten with the new document.
          type: string

        title:
          type: string
          pattern: /[\w][\w\d \-_\.]*\-_\.]*/
        concern:
          type: string
        filename:
          description: Only for /addfile
          type: string
        filepath:
          description: Only for /addfile
          type: string
        contents:
          description: Only for /addindex
          type: string
          format: base64
    newFile:
      type: object
      required:
        - metadata
        - payload
      properties:
        metadata:
          type: object
          $ref: "#/components/schemas/newDocument"
        payload:
          type: string
          format: base64

    jsonQuery:
      description: For more informations on json Queries, see Solr documentation
      type: object
      required:
        - query
      properties:
        query:
          description: A Lucene conformant query expression, e.g. "title:someTitle&author:johndoe" (aka q)
          type: string
        limit:
          description: Number of results per call (aka rows)
          type: number
        offset:
          description: offset of first result (aka start)
          type: number
        filter:
          description: filter expressen (aka fl)
          type: string
        sort:
          description: A sort expression, such as "title asc"
          type: string
        facet:
          type: object
    solrResponse:
      description: Result of a successful query to Lucinda
      type: object
      properties:
        numFound:
          type: number
        start:
          type: number
        docs:
          type: array
          items:
            description: application specific document objects
            type: object