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: 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: All search results
          content:
            application/json:
              schema: 
                type: object
                properties: 
                  data: 
                    type: array
                    items: 
                      type: object
                    description: Results as an array of objects
                  sparqlQuery:
                    type: string
                    description: The SPARQL query that was used for the results
  /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: integer
                  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
          required: true
          description: The class of the facet
        - in: path
          name: id
          schema: 
            type: string
          required: true
          description: The id of the facet
      requestBody:
        required: true
        content: 
          application/json:
            schema:
              type: object
              properties:
                sortBy:
                 type: string
                sortDirection:
                  type: string 
                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
          required: true
          description: The class of the resource
        - in: path
          name: uri
          schema: 
            type: string
          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
          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: 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