openapi: 3.0.3
info:
  title: Sampo-UI API
  description: |
    This API provides routes for the following search paradigms:
    *faceted search*, *full text search*, and *federated full text or spatial search*. 
    In general the purpose of the API is to
    
    1. convert a request into a SPARQL query using a set of query templates and configurations, 
    2. run the query against a preconfigured SPARQL endpoint,
    3. process the SPARQL results with a preconfigured result mapper, and  
    4. return them in JSON or CSV format.

    The routes related to faceted search accept only POST requests, because the
    facet selection arrays may become so large that they need to be delived in the body of the request. 
    See the schemas for each route for more info about the parameters.
  version: 1.0.0
servers:
  - url: /api/v1
paths:
  /faceted-search/{resultClass}/paginated:
    post:
      summary: Return faceted search results with pagination
      parameters:
      - in: path
        name: resultClass
        schema: 
          type: string
          example: perspective1
        required: true
        description: The class of the results
      requestBody:
        required: true
        content: 
          application/json:
            schema:
              type: object
              properties:
                page:
                  type: integer
                  default: 0
                  example: 0 
                pagesize:
                  type: integer
                  default: 10
                  example: 10
                sortBy:
                 type: string
                 nullable: true
                 default: null
                 example: null
                sortDirection:
                  type: string 
                  nullable: true
                  default: null
                  example: null
                constraints:
                  type: array
                  items: 
                    type: object
                  nullable: true
                  default: null
                  example: null  
      responses:
        '200':   
          description: Paginated search results
          content:
            application/json:
              schema: 
                type: object
                properties: 
                  data: 
                    type: array
                    items: 
                      type: object
                    description: Results as an array of objects
                  page:
                    type: integer
                    description: The current page
                  pagesize:
                    type: integer
                    description: Items per page
                  resultClass:
                    type: string
                    description: The class of the results    
                  sparqlQuery:
                    type: string
                    description: The SPARQL query that was used for the results
  /faceted-search/{resultClass}/all:
    post:
      summary: Return all search results
      parameters:
      - in: path
        name: resultClass
        schema: 
          type: string
          example: placesMsProduced
        required: true
        description: The class of the results
      requestBody:
        required: true
        content: 
          application/json:
            schema:
              type: object
              properties:
                constraints:
                  type: array
                  items: 
                    type: object
                  nullable: true
                  default: null
                  example: null  
      responses:
        '200':   
          description: All search results
          content:
            application/json:
              schema: 
                type: object
    get:
        summary: Return all search results as a CSV file
        parameters:
        - in: path
          name: resultClass
          schema: 
            type: string
            example: perspective1
          required: true
          description: The class of the results
        - in: query
          name: facetClass
          schema: 
            type: string
            example: perspective1
          required: true
          description: The class for facet configs
        - in: query
          name: constraints
          required: false
          content: 
            application/json:
              schema:
                type: array
        - in: query
          name: resultFormat
          schema: 
            type: string
            example: csv
          required: true
          description: Result format, only support for CSV for now.
        responses:
          '200':   
            description: All search results as a CSV file
            content:
              text/plain:
                schema:
                  type: string
                  format: binary                  
  /faceted-search/{resultClass}/count:
    post:
      summary: Return the total count of the faceted search results
      parameters:
      - in: path
        name: resultClass
        schema: 
          type: string
          example: perspective1
        required: true
        description: The class of the results
      requestBody:
        required: true
        content: 
          application/json:
            schema:
               type: object  
               properties: 
                   constraints:
                      type: array
                      items: 
                        type: object
                      nullable: true
                      default: null  
                      example: null
      responses:
        '200':   
          description: The total count of the faceted search results
          content:
            application/json:
              schema: 
                type: object
                properties: 
                  data: 
                    type: string
                  sparqlQuery:
                    type: string
                  resultClass: 
                    type: string  
                  constraints:
                    type: array
                    nullable: true
                    items: 
                      type: object
                    default: null          
  /faceted-search/{facetClass}/facet/{id}:
    post:
      summary: Return values for a single facet
      parameters:
        - in: path
          name: facetClass
          schema: 
            type: string
            example: perspective1
          required: true
          description: The class of the facet
        - in: path
          name: id
          schema: 
            type: string
            example: language
          required: true
          description: The id of the facet
      requestBody:
        required: true
        content: 
          application/json:
            schema:
              type: object
              properties:
                sortBy:
                 type: string
                 example: instanceCount
                sortDirection:
                  type: string 
                  example: desc
                constraints:
                    type: array
                    items: 
                      type: object
                    nullable: true
                    default: null
                constrainSelf:
                  type: boolean
                  default: false           
      responses:
        '200':   
          description: Facet values
          content:
            application/json:
              schema: 
                type: object
                properties: 
                  data:
                    oneOf:
                      - type: array
                        items: 
                          type: object
                      - type: object 
                    description: Facet values as an array of objects (checkbox facets) 
                      or as a single object (timespan facets).              
                  flatData: 
                    type: array
                    items: 
                      type: object
                    description: Facet values as an array of objects with no hierarchy  
                  id:
                    type: string
                    description: The id of facet
                  sparqlQuery:
                    type: string
                    description: The SPARQL query that was used for the values of the facet                 
  /{resultClass}/page/{uri}:
    post: 
      summary: Return information about a single resource, optionally applying facet filters
      parameters:
        - in: path
          name: resultClass
          schema: 
            type: string
            example: perspective1
          required: true
          description: The class of the resource
        - in: path
          name: uri
          schema: 
            type: string
            example: http://ldf.fi/mmm/manifestation_singleton/bibale_10003
          required: true
          description: The URI of the resource
      requestBody:
        required: true
        content: 
          application/json:
            schema:
              type: object
              properties:
                facetClass:
                 type: string
                constraints:
                    type: array
                    items: 
                      type: object
                    nullable: true
                    default: null
      responses:
        '200':
          description: Information about a single resource
          content:
            application/json:
              schema: 
                type: object
                properties: 
                  data: 
                    type: array
                    items: 
                      type: object
                    description: An array containing one object describing the resource
                  sparqlQuery:
                    type: string
                    description: The SPARQL query that was used for retrieving the metadata
  /full-text-search:
    get:
      summary: Full text search
      parameters:
        - in: query
          name: q
          schema: 
            type: string
          required: true
          allowReserved: true 
          description: The query string
      responses:
        '200':
          description: Full text search results
          content:
            application/json:
              schema: 
                type: object
                properties: 
                  data: 
                    type: array
                    items: 
                      type: object
                    description: An array of objects
                  sparqlQuery:
                    type: string
                    description: The SPARQL query that was used for retrieving the results    
  /federated-search:
    get:
      summary: Federated search can be used for retrieving the initial result set from multiple SPARQL 
        endpoints for client-side faceted search.
      parameters:
        - in: query
          name: perspectiveID
          schema: 
            type: string
          required: true  
        - in: query
          name: dataset
          schema:
            type: array
            items: 
              type: string
          explode: true
          required: true
        - in: query
          name: q
          schema: 
            type: string 
          allowReserved: true  
          description: The query string
        - in: query
          name: latMin
          schema: 
            type: number
        - in: query
          name: longMin
          schema: 
            type: number
        - in: query
          name: latMax
          schema: 
            type: number
        - in: query
          name: longMax
          schema: 
            type: number
      responses:
        '200':
          description: Federated search results
          content:
            application/json:
              schema: 
                type: array
                items:
                  type: object
                description: Search results from multiple SPARQL endpoints
                      merged into a single array
  /wfs:
    get:
      summary: Make preconfigured Web Feature Service (WFS) API calls via the backend. 
      parameters:
        - in: query
          name: layerID
          schema: 
            type: array
            items: 
              type: string
          explode: true
          required: true
      responses:
        '200':
          description: An array of GeoJSON layers.
          content:
            application/json:
              schema:
                type: array
  /fha-wms:
    get:
      summary: Route for password protected WMS layers.
      parameters:
        - in: query
          name: service
          schema:
            type: string
          required: true
        - in: query
          name: request
          schema:
            type: string
          required: true 
        - in: query
          name: layers
          schema:
            type: string
          required: true  
        - in: query
          name: styles
          schema:
            type: string
          allowEmptyValue : true
          required: true  
        - in: query
          name: format
          schema:
            type: string
          required: true    
        - in: query
          name: transparent
          schema:
            type: boolean
          required: true
        - in: query
          name: version
          schema:
            type: string
          required: true   
        - in: query
          name: width
          schema:
            type: number
          required: true
        - in: query
          name: height
          schema:
            type: number
          required: true
        - in: query
          name: crs
          schema:
            type: string
          required: true 
        - in: query
          name: bbox
          schema:
            type: string
          allowReserved: true  
          required: true       
      responses:
        '200':
          description: Image
          content:
            image/jpeg:
              schema:
                type: string
                format: binary     
  /nls-wmts:
    get:
      summary: Route for NLS WMTS API. Only for contract customers. 
      parameters:
        - in: query
          name: layerID
          schema: 
            type: string
          required: true
        - in: query
          name: x
          schema: 
            type: string
          required: true
        - in: query
          name: y 
          schema: 
            type: string
          required: true
        - in: query
          name: z
          schema: 
            type: string
          required: true  
      responses:
        '200':
          description: An array of GeoJSON layers.
          content:
            application/json:
              schema:
                type: array    
  /nls-wmts-open:
    get:
      summary: Route for NLS WMTS API, free but requires an API key.
      parameters:
        - in: query
          name: layerID
          schema: 
            type: string
          required: true
        - in: query
          name: x
          schema: 
            type: string
          required: true
        - in: query
          name: y 
          schema: 
            type: string
          required: true
        - in: query
          name: z
          schema: 
            type: string
          required: true  
      responses:
        '200':
          description: An array of GeoJSON layers.
          content:
            application/json:
              schema:
                type: array                    
  /nls-vectortiles-open:
    get:
      summary: Route for NLS vectortiles API, free but requires an API key. 
      responses:
        '200':
          description: Styles for vector tiles as JSON
          content:
            application/json:
              schema:
                type: object
  /void/{resultClass}:
    get:
      summary: Retrieve a VoID description
      parameters:
        - in: path
          name: resultClass
          schema: 
            type: string
            example: perspective1KnowledgeGraphMetadata
          required: true
      responses:
        '200':
          description: VoID description as JSON.
          content:
            application/json:
              schema:
                type: object