generic-adapter-rest-OpenAPI.yaml

openapi: 3.0.1
info:
  title: InterConnect Generic Adapter REST API Documentation
  description: This is OpenAPI documentation for REST API provided by the InterConnect Generic Adapter.
  version: '2.2.2'
servers:
  - url: 'http://localhost:9090'
    description: Generated server url
tags:
  - name: smart connector - life cycle
    description: methods for interacting with the Knowledge Engine and managing smart connector instance
  - name: smart connector - knowledge interaction life cycle
    description: methods for interacting with the smart connector instance and managing knowledge interactions for your service
  - name: smart connector - proactive interactions
    description: methods for exchanging data with other services in proactive manner
  - name: smart connector - reactive interactions
    description: methods for exchanging data with other services in reactive manner
  - name: service store - authentication controller
    description: methods for performing authentication and authorization with the service store
#  - name: service store - docker controller (to be added)
#    description: methods for managing docker containers of the registered interoperable services
  - name: service store - generic adapter controller
    description: methods for managing generic adapter instance for registered services
  - name: service store - service controller
    description: methods for managing service store catalog of interoperable services
  - name: generic adapter - control panel controller
    description: methods for configuring generic adapter instance
  - name: smart connector - lease
paths:
  /smartconnector/post:
    post:
      summary: Execute the given Post Knowledge Interaction with the given binding set. It is possible to target this post to a specific Knowledge Base by including RecipientSelector in the requestBody.
      tags:
        - smart connector - proactive interactions
      operationId: postKnowledgeInteraction
      parameters:
        - name: KnowledgeBaseId
          in: header
          required: true
          schema:
            type: string
        - name: KnowledgeInteractionId
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        description: Either a BindingSet only or a RecipientSelector and BindingSet. The recipient selector currently only supports a single Knowledge-Base-Id, but might be extended in the future. The keys bindings must be complete, and they must correspond to the binding keys that were defined in the knowledge interaction.
        content:
          application/json; charset=UTF-8:
            schema:
              oneOf:
                - $ref: '#/components/schemas/RecipientAndBindingSet'
                - $ref: '#/components/schemas/recipientSelector'
                - $ref: '#/components/schemas/BindingSet'
            examples:
              bindingset only:
                value:
                  - p: <http://www.tno.nl/s1>
                    q: <http://www.tno.nl/p1>
                    r: <http://www.tno.nl/o1>
              recipient and bindingset:
                value:
                  recipientSelector:
                    knowledgeBases:
                      - http://www.tno.nl/kb2
                      - http://www.tno.nl/kb3
                  bindingSet:
                    - p: <http://www.tno.nl/s1>
                      q: <http://www.tno.nl/p1>
                      r: <http://www.tno.nl/o1>
              single recipient and bindingset:
                value:
                  recipientSelector:
                    singleKnowledgeBase: http://www.tno.nl/kb1
                  bindingSet:
                    - p: <http://www.tno.nl/s1>
                      q: <http://www.tno.nl/p1>
                      r: <http://www.tno.nl/o1>         
      responses:
        '200':
          description: If the post was successful it optionally returns all
            result variable bindings together with all exchange infos. The
            exchange info shows the other Knowledge Bases that contributed to
            the answer with timing, initiator information.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/PostResult'
        '401':
          description: If not authorized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '404':
          description: If a Knowledge Interaction for the given Knowledge-Base-Id and Knowledge-Interaction-Id cannot be found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '500':
          description: If an internal server error occurs.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
  /smartconnector/RDF/post:
    post:
      summary: Execute the given Post Knowledge Interaction with the given binding set. It is possible to target this post to a specific Knowledge Base by including RecipientSelector in the requestBody.
      tags:
        - smart connector - proactive interactions
      operationId: postKnowledgeInteractionRDFBindings
      parameters:
        - name: KnowledgeBaseId
          in: header
          required: true
          schema:
            type: string
        - name: KnowledgeInteractionId
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        description: Either a BindingSet only or a RecipientSelector and BindingSet in the shape of RDP triples. The recipient selector currently only supports a single Knowledge-Base-Id, but might be extended in the future. The keys bindings must be complete, and they must correspond to the binding keys that were defined in the knowledge interaction in the shape of RDP triples.
        content:
          application/json; charset=UTF-8:
            schema:
              oneOf:
                - $ref: '#/components/schemas/RecipientAndRDFBindingSet'
                - $ref: '#/components/schemas/RDFBindingSet'
            examples:
              bindingset only:
                value:
                  - <http://x.org/s> <p2> <http://x.org/o3> . <http://x.org/s> <p2> <http://x.org/o2> . <http://x.org/s> <p2> <http://x.org/o1> . <http://x.org/s> <p1> <http://x.org/o> .
              recipient and bindingset:
                value:
                  recipientSelector:
                    knowledgeBases:
                      - http://www.tno.nl/kb2
                      - http://www.tno.nl/kb3
                  RDFBindingSet: <http://x.org/s> <p2> <http://x.org/o3> . <http://x.org/s> <p2> <http://x.org/o2> . <http://x.org/s> <p2> <http://x.org/o1> . <http://x.org/s> <p1> <http://x.org/o> .
              single recipient and bindingset:
                value:
                  recipientSelector:
                    singleKnowledgeBase: http://www.tno.nl/kb1
                  RDFBindingSet: <http://x.org/s> <p2> <http://x.org/o3> . <http://x.org/s> <p2> <http://x.org/o2> . <http://x.org/s> <p2> <http://x.org/o1> . <http://x.org/s> <p1> <http://x.org/o> .
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /smartconnector/ki/register-ask-answer:
    post:
      summary: Register a Knowledge Interaction with the Smart Connector of the given Knowledge Base Id.
      tags:
        - smart connector - knowledge interaction life cycle
      operationId: registerKnowledgeInteractionAskAnswer
      parameters:
        - name: KnowledgeBaseId
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json; charset=UTF-8:
            schema:
              $ref: '#/components/schemas/RegisterKnowledgeInteractionAskAnswer'
            examples:
              ASK without prefixes:
                value:
                  knowledgeInteractionType: AskKnowledgeInteraction
                  graphPattern: "?a <http://example.org/isRelatedTo> ?b ."
              ASK with prefixes:
                value:
                  knowledgeInteractionType: AskKnowledgeInteraction
                  graphPattern: "?a rdf:type ex:Something ."
                  prefixes:
                    rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
                    ex: "http://example.org/"
              ASK with name and prefixes:
                value:
                  knowledgeInteractionType: AskKnowledgeInteraction
                  knowledgeInteractionName: books-by-shakespeare
                  graphPattern: "?a rdf:type ex:Book . ?a ex:hasAuthor ex:Shakespeare"
                  prefixes:
                    rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
                    ex: "http://example.org/"
      responses:
        '200':
          description: If the Knowledge Interaction is successfully registered, it returns the knowledge interaction id.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/KnowledgeInteractionId'
              example:
                knowledgeInteractionId:
                  https://www.interconnectproject.eu/knowledge-engine/knowledgebase/example/a-reacting-kb/42
        '400':
          description: If the Knowledge Interaction is not successfully registered.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '401':
          description: If not authorized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '404':
          description: If a Smart Connector for the given Knowledge-Base-Id cannot be found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
  /smartconnector/ki/register-post-react:
    post:
      summary: Register a Knowledge Interaction with the Smart Connector of the given Knowledge Base Id.
      tags:
        - smart connector - knowledge interaction life cycle
      operationId: registerKnowledgeInteractionPostReact
      parameters:
        - name: KnowledgeBaseId
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json; charset=UTF-8:
            schema:
              $ref: '#/components/schemas/RegisterKnowledgeInteractionPostReact'
            examples:
              REACT without prefixes:
                value:
                  knowledgeInteractionType: ReactKnowledgeInteraction
                  argumentGraphPattern:
                    ?a rdf:type ex:Measurement .
                    ?a ex:hasValueInMeters ?b .
                  resultGraphPattern:
                    ?a rdf:type ex:Measurement .
                    ?a ex:hasValueInYards ?b .
              REACT with prefixes:
                value:
                  knowledgeInteractionType: ReactKnowledgeInteraction
                  argumentGraphPattern:
                    ?a rdf:type ex:Measurement .
                    ?a ex:hasValueInMeters ?b .
                  resultGraphPattern:
                    ?a rdf:type ex:Measurement .
                    ?a ex:hasValueInYards ?b .
                  prefixes:
                    rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
                    ex: "http://example.org/"
              REACT with name and prefixes:
                value:
                  knowledgeInteractionType: ReactKnowledgeInteraction
                  knowledgeInteractionName: interaction-name
                  argumentGraphPattern:
                    ?a rdf:type ex:Measurement .
                    ?a ex:hasValueInMeters ?b .
                  resultGraphPattern:
                    ?a rdf:type ex:Measurement .
                    ?a ex:hasValueInYards ?b .
                  prefixes:
                    rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
                    ex: "http://example.org/"
      responses:
        '200':
          description: If the Knowledge Interaction is successfully registered, it returns the knowledge interaction id.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/KnowledgeInteractionId'
              example:
                knowledgeInteractionId:
                  https://www.interconnectproject.eu/knowledge-engine/knowledgebase/example/a-reacting-kb/42
        '400':
          description: If the Knowledge Interaction is not successfully registered.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '401':
          description: If not authorized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '404':
          description: If a Smart Connector for the given Knowledge-Base-Id cannot be found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
  /smartconnector/handle/send:
    post:
      summary: Send the answer or reaction of the last long polling handle
        request back to the Smart Connector of the given Knowledge-Base-Id. 
      description: For more information about boolean parameter <i>shortPolling</i> check <a href="https://gitlab.inesctec.pt/interconnect/generic-adapter/-/blob/master/docs/05_REST.md" target="_blank">docs</a>.
      tags:
        - smart connector - reactive interactions
      operationId: sendAnswerReaction
      parameters:
        - name: shortPolling
          in: query
          required: false
          schema:
            type: boolean
        - name: KnowledgeBaseId
          in: header
          required: true
          schema:
            type: string
        - name: KnowledgeInteractionId
          in: header
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HandleResponse'
        required: true
      responses:
        '200':
          description: If the answer is successfully processed by your smart connector.
        '400':
          description: If the answer was not successfully processed by the Knowledge Base's smart connector.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '401':
          description: If not authorized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '404':
          description: If a Handle Request Id or Knowledge Interaction for the
            given Knowledge-Base-Id and Knowledge-Interaction-Id cannot be found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
  /smartconnector/RDF/handle/send:
    post:
      summary: Send the answer or reaction of the last long polling handle
        request back to the Smart Connector of the given Knowledge-Base-Id.
      tags:
        - smart connector - reactive interactions
      operationId: sendAnswerReactionRDF
      parameters:
        - name: KnowledgeBaseId
          in: header
          required: true
          schema:
            type: string
        - name: KnowledgeInteractionId
          in: header
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RDFBindingSet'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /smartconnector/create:
    post:
      summary: Create a new Smart Connector for the given Knowledge Base.
      tags:
        - smart connector - life cycle
      operationId: createSmartConnector
      requestBody:
        required: true
        content:
          application/json; charset=UTF-8:
            schema:
              $ref: '#/components/schemas/CreateSmartConnector'
            examples:
              without lease:
                value:
                  knowledgeBaseId: http://example.org/a-knowledge-base-id
                  knowledgeBaseName: Example Knowledge Base
                  knowledgeBaseDescription: This is a detailed description
              with 60 seconds lease:
                value:
                  knowledgeBaseId: http://example.org/a-knowledge-base-id
                  knowledgeBaseName: Example Knowledge Base
                  knowledgeBaseDescription: This is a detailed description
                  leaseRenewalTime: 60
                description:
                  The created smart connector will be cleaned up automatically
                  after about 60 seconds. To postpone the cleanup, your
                  knowledge base has to call /smartconnector/lease/renew to extend the lease
                  by 60 seconds.
              with reasoner enabled:
                value:
                  knowledgeBaseId: http://example.org/a-knowledge-base-id
                  knowledgeBaseName: Example Knowledge Base
                  knowledgeBaseDescription: This is a detailed description
                  reasonerEnabled: true
                description:
                  The reasoner is disabled by default. If enabled, the created smart 
                  connector will use a reasoner to orchestrate the data exchange. 
                  This increases the flexibility, but can decrease the performance 
                  and cause unexpected behaviour, for now. This flexibility means the 
                  smart connector will automatically try to combine data coming 
                  from different knowledge bases or try to convert units of measures. 
                  If the reasoner is disabled, the smart connector will only exchange 
                  data with other smart connectors if their graph patterns match 
                  entirely (apart from ordering and variable names).
      responses:
        '200':
          description: If the Smart Connector for the given Knowledge Base is successfully created.
        '400':
          description: If the creation of the Smart Connector for the given Knowledge Base failed.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '401':
          description: If not authorized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
  /smartconnector/ask:
    post:
      summary: Execute the given Ask Knowledge Interaction with the given binding set. It is possible to target this ask to a specific Knowledge Base by including a RecipientSelector in the requestBody.
      tags:
        - smart connector - proactive interactions
      parameters:
        - name: KnowledgeBaseId
          in: header
          required: true
          description: The Knowledge Base Id for which to execute the ask.
          schema:
            type: string
        - name: KnowledgeInteractionId
          in: header
          required: true
          description: The Ask Knowledge Interaction Id to execute.
          schema:
            type: string
      requestBody:
        required: true
        description: Either a BindingSet only or a RecipientSelector and BindingSet. The recipient selector supports multiple Knowledge-Base-Id. The keys (i.e. variables) in the BindingSet are allowed to be incomplete, but they must correspond to the keys that were defined in the graph pattern of the knowledge interaction.
        content:
          application/json; charset=UTF-8:
            schema:
              oneOf:
                - $ref: '#/components/schemas/RecipientAndBindingSet'
                - $ref: '#/components/schemas/recipientSelector'
                - $ref: '#/components/schemas/BindingSet'
            examples:
              bindingset only:
                value:
                  - p: <http://www.tno.nl/s1>
                    q: <http://www.tno.nl/p1>
                    r: <http://www.tno.nl/o1>
              recipient and bindingset:
                value:
                  recipientSelector:
                    knowledgeBases:
                      - http://www.tno.nl/kb2
                      - http://www.tno.nl/kb3
                  bindingSet:
                    - p: <http://www.tno.nl/s1>
                      q: <http://www.tno.nl/p1>
                      r: <http://www.tno.nl/o1>
              single recipient and bindingset:
                value:
                  recipientSelector:
                    singleKnowledgeBase: http://www.tno.nl/kb1
                  bindingSet:
                    - p: <http://www.tno.nl/s1>
                      q: <http://www.tno.nl/p1>
                      r: <http://www.tno.nl/o1>
      responses:
        '200':
          description: If the ask was successful it returns all found variable
            bindings together with additional exchange info. The returned bindings form 
            a set and there is no quaranteed ordering. The exchange info shows the other 
            Knowledge Bases that contributed to the answer with timing, initiator information.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/AskResult'
        '400':
          description: If the ask failed.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '401':
          description: If not authorized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '404':
          description: If a Knowledge Interaction for the given Knowledge-Base-Id and Knowledge-Interaction-Id cannot be found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '500':
          description: If an internal server error occurs.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
  /smartconnector/RDF/ask:
    post:
      summary: Execute the given Ask Knowledge Interaction with the given binding set. It is possible to target this ask to a specific Knowledge Base by including a RecipientSelector in the requestBody.
      tags:
        - smart connector - proactive interactions
      operationId: askKnowledgeInteractionRDFBindings
      parameters:
        - name: KnowledgeBaseId
          in: header
          required: true
          schema:
            type: string
        - name: KnowledgeInteractionId
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json; charset=UTF-8:
            schema:
              oneOf:
                - $ref: '#/components/schemas/RecipientAndRDFBindingSet'
                - $ref: '#/components/schemas/RecipientAndRDFBindingSet'
                - $ref: '#/components/schemas/RDFBindingSet'
            examples:
              bindingset only:
                value:
                  - <http://x.org/s> <p2> <http://x.org/o3> . <http://x.org/s> <p2> <http://x.org/o2> . <http://x.org/s> <p2> <http://x.org/o1> . <http://x.org/s> <p1> <http://x.org/o> .
              recipient and bindingset:
                value:
                  recipientSelector:
                    knowledgeBases:
                      - http://www.tno.nl/kb2
                      - http://www.tno.nl/kb3
                  RDFBindingSet: <http://x.org/s> <p2> <http://x.org/o3> . <http://x.org/s> <p2> <http://x.org/o2> . <http://x.org/s> <p2> <http://x.org/o1> . <http://x.org/s> <p1> <http://x.org/o> . 
              single recipient and bindingset:
                value:
                  recipientSelector:
                    singleKnowledgeBase: http://www.tno.nl/kb1
                  RDFBindingSet: <http://x.org/s> <p2> <http://x.org/o3> . <http://x.org/s> <p2> <http://x.org/o2> . <http://x.org/s> <p2> <http://x.org/o1> . <http://x.org/s> <p1> <http://x.org/o> .          
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /servicestore/service/add-service:
    post:
      summary: Register new service in the service store
      tags:
        - service store - service controller
      operationId: registerService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterServiceForm'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: string
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /servicestore/login:
    post:
      summary: Authenticate user of the service
      tags:
        - service store - authentication controller
      operationId: login
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginForm'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: object
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /servicestore/adapter/register:
    post:
      summary: Register generic adapter instance for the service
      tags:
        - service store - generic adapter controller
      operationId: registerAdapter
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterAdapterForm'
            examples:
              without assetID:
                value:
                    hash: a425a89c7687447ec0b4360c5cade4391963ceadda00c570a4a9
                    language: Java
                    transport: HTTP
                description:
                    By default an adapter ID will be randomly generated. This output should be used to create the smart connector. 
              with assetID:
                value:
                  hash: a425a89c7687447ec0b4360c5cade4391963ceadda00c570a4a9
                  language: Java
                  transport: HTTP
                  assetID: name-for-my-adpter
                description:
                  By default an adapter ID will be randomly generated. This output should be used to create the smart connector. 
                  If a specific adapterID is specified, the assetID will be used to register the adapter and becomes the output to create the smart connector. 
                  In case case, the user must ensure no colisions by having a unique assetID.
        required: true
      responses:
        '200':
          description: OK - If the adapter is successfully registered.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/RegisterAdapterResult'
              example:
                adapterID:
                  https://ke.interconnectproject.eu/adapter/generic-adapter-test-asset2
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '406':
          description: Not Acceptable - The adapter ID that is being registered already exists.  
  /smartconnector/ki/get:
    get:
      summary: Get all KnowledgeInteractions for a given Knowledge-Base-Id
      tags:
        - smart connector - knowledge interaction life cycle
      operationId: getKnowledgeInteractions
      parameters:
        - name: KnowledgeBaseId
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: If the Knowledge Interactions were successfully returned.
          content:
            application/json; charset=UTF-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KnowledgeInteraction'
        '401':
          description: If not authorized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
  /smartconnector/handle/start:
    get:
      summary: Start waiting for a handle request for the given Knowledge Base Id.
      description: Note that this is a long polling HTTP call.
        It will block until the client is expected to handle something in which
        case it returns. When it returns, a new request to this same endpoint
        should be immediately made to receive further handle requests. (*** What
        if one or more handle requests came in in the meantime? ***) All handle
        requests (both for Answer and React Knowledge Interactions) for the
        given Knowledge-Base-Id will be received via a single long polling http
        connection. The Knowledge Interaction Id can be used to distinguish
        between different Knowledge Interactions. The <i>handle request id</i>
        (which is unique per Knowledge Base Id) should be used when sending the
        result back to the server. It allows the server to know which handle
        request you are reacting to in the <i>post</i> method of this path. </b>
        For more information about boolean parameter <i>shortPolling</i> check <a href="https://gitlab.inesctec.pt/interconnect/generic-adapter/-/blob/master/docs/05_REST.md" target="_blank">docs</a>.
      tags:
        - smart connector - reactive interactions
      operationId: startWaitingForHandleRequest
      parameters:
        - name: shortPolling
          in: query
          required: false
          schema:
            type: boolean
        - name: KnowledgeBaseId
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: If a request to handle a particular Knowledge Interaction Id comes in with a binding set.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/HandleRequest'
              example:
                knowledgeInteractionId: http://example.org/ki/your-knowledge-interaction-id
                handleRequestId: 1
                bindingSet:
                  - a: <http://example.org/some-incoming-value>
                    b: <http://example.org/another-incoming-value>
                requestingKnowledgeBaseId: http://example.org/knowledge-base-id-of-requesting-side
        '202':
          description: No problems, but please reinitiate the long polling request. To prevent very long open connections (which might cause problems for some systems), we regularly return with status code 202 to renew the long polling connection. Note that no handlerequests will be missed, because these are queued automatically.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '401':
          description: If not authorized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '404':
          description: If a Knowledge Interaction for the given Knowledge-Base-Id and Knowledge-Interaction-Id cannot be found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '409':
          description: Only one connection per Knowledge-Base-Id is allowed and we already have one.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '410':
          description: This long polling connection has stopped because the server will shut down, please do <b>not</b> reinitiate this request.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '500':
          description: If a problem occurred. Please reinitiate this long polling http call.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
  /smartconnector/handle/collect-reply:
    get:
      tags:
        - smart connector - reactive interactions
      operationId: colectNoPollingReply
      parameters:
        - name: replyCollectionHash
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: object
        '204':
          description: No content
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '401':
          description: If not authorized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
  /smartconnector/get-all-or-one:
    get:
      summary: Either get all available Smart Connectors or a specific one if the Knowledge-Base-Id is provided.
      tags:
        - smart connector - life cycle
      parameters:
        - name: KnowledgeBaseId
          in: header
          required: false
          description: The knowledge base id who's Smart Connector information you would like to have.
          schema:
            type: string
      responses:
        '200':
          description: A list of Smart Connectors. It will have only a single element if the Knowledge-Base-Id was provided.
          content:
            application/json; charset=UTF-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SmartConnector'
        '401':
          description: If not authorized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '404':
          description: If there is no Smart Connector for the given Knowledge-Base-Id.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '500':
          description: If a problem occurred.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
  /servicestore/users/userinfo:
    get:
      summary: Get information about the reistered user
      tags:
        - service store - authentication controller
      operationId: getUserInfo
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceStoreUser'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  '/servicestore/services/{id}':
    post:
      summary: Get basic information about the service with service_id
      tags:
        - service store - service controller
      operationId: getServiceDetail
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  '/servicestore/services/services/{serviceId}/details':
    get:
      summary: Now working.. It should return User's onboardings
      tags:
        - service store - service controller
      operationId: getUserOnboardings
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
  /servicestore/service-list:
    get:
      summary: Get list of titles and service_ids of all registered services
      tags:
        - service store - service controller
      operationId: getAllServiceList
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /servicestore/my-services:
    get:
      summary: get list of titles and service_ids of all services belonging to the registered user
      tags:
        - service store - service controller
      operationId: getMyServiceList
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /servicestore/adapter/adapter-list:
    get:
      summary: Get list of generic adapter_ids for all services
      tags:
        - service store - generic adapter controller
      operationId: getAdapters
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Adapter'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /smartconnector/ki/unregister:
    delete:
      summary: Unregister the given Knowledge Interaction with the Smart Connector of the given Knowledge Base
      tags:
        - smart connector - knowledge interaction life cycle
      operationId: unregisterKnowledgeInteraction
      parameters:
        - name: KnowledgeBaseId
          in: header
          required: true
          schema:
            type: string
        - name: KnowledgeInteractionId
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: If the Knowledge Interaction is successfully unregistered.
        '400':
          description: If unregistering the Knowledge Interaction failed.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '401':
          description: If not authorized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '404':
          description: If a Knowledge Interaction or Knowledge Interaction for
            the given Knowledge-Base-Id and Knowledge-Interaction-Id cannot be
            found.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
  /smartconnector/delete:
    delete:
      summary: Delete the Smart Connector belonging to the given Knowledge Base
      tags:
        - smart connector - life cycle
      operationId: deleteSmartConnector
      parameters:
        - name: KnowledgeBaseId
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: If the Smart Connector for the given Knowledge Base is successfully deleted.
        '401':
          description: If not authorized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '404':
          description: If there is no Smart Connector for the given Knowledge-Base-Id.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
  /smartconnector/lease/renew:
    put:
      summary: Renew the lease of a Smart Connector.
      tags:
        - smart connector - lease
      parameters:
        - name: KnowledgeBaseId
          in: header
          required: true
          description: The ID of the Knowledge Base whose lease you wish to renew.
          schema:
            type: string
      responses:
        '200':
          description: The renewed lease
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/SmartConnectorLease'
        '400':
          description: The request was faulty.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '401':
          description: If not authorized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '404':
          description: The Knowledge Base doesn't exist (anymore), or doesn't have a lease.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'

  /getConfiguration:
    get:
      summary: Get configuration and state for this generic adapter isntance
      tags:
        - generic adapter - control panel controller
      responses:
        '200':
          description: The Generic adapter configuration
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ConfigResult'
              example:
                localAddress:
                  http://localhost:9090 
                keAddress:
                  https://ke.interconnectproject.eu/rest
        '401':
          description: If not authorized.
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseMessage'                
components:
  schemas:
    AuthorizedUser:
      type: object
      properties:
        access_token:
          type: string
        expires_in:
          type: integer
        authorized_destination_adapters:
          type: array
          items:
            type: string
    SmartConnector:
      type: object
      required: [knowledgeBaseId, knowledgeBaseName, knowledgeBaseDescription]
      properties:
        knowledgeBaseId:
          type: string
        knowledgeBaseName:
          type: string
        knowledgeBaseDescription:
          type: string
        leaseRenewalTime:
          type: integer
          minimum: 30
          maximum: 3600
          description: Include this property if you want to have your knowledge
            base automatically unregistered when you don't renew your lease. Expiry
            is checked periodically, so your knowledge base may actually be
            valid for longer than the given time.
        reasonerEnabled:
          type: boolean
          description: Include this optional property if you want to specify whether 
            the smart connector should use a reasoner or a matcher to orchestrate data 
            exchange. In general the reasoner increases the flexibility, but decreases 
            the performance. The matcher decreases the flexibility, but increases 
            the performance.
    RecipientAndBindingSet:
      type: object
      required: [recipientSelector, bindingSet]
      properties:
        recipientSelector:
          $ref: '#/components/schemas/RecipientSelector'
        bindingSet:
          $ref: '#/components/schemas/BindingSet'
    RecipientAndRDFBindingSet:
      type: object
      required: [recipientSelector, RDFBindingSet]
      properties:
        recipientSelector:
          $ref: '#/components/schemas/RecipientSelector'
        RDFBindingSet:
          $ref: '#/components/schemas/RDFBindingSet'
    RecipientSelector:
      type: object
      description: Include a RecipientSelector with your message to ensure it only arrives at the specified Knowledge Base(s).
      properties:
        knowledgeBases:
          type: array
          minItems: 1
          description: List of Knowledge Base IDs, specifying the Knowledge Bases that can receive the message. No other Knowledge Bases will receive it.
          items:
            type: string
        singleKnowledgeBase:
          type: string
          description: >
            Knowledge Base ID of the recipient. Deprecated: Please use the 'knowledgeBases' property with a list of lenght 1 instead. 
    recipientSelector:
      type: object
      description: Include a RecipientSelector with your message to ensure it only arrives at the specified Knowledge Base(s).
      properties:
        singleKnowledgeBase:
          type: string 
          description: >
            Knowledge Base ID of the recipient. Deprecated: Please use the 'knowledgeBases' property with a list of lenght 1 instead. 
    ResponseMessage:
      type: object
      properties:
        messageType:
          type: string
        message: 
          type: string
    PostExchangeInfo:
      type: object
      properties:
        initiator:
          type: string
          enum:
            - knowledgeBase
            - reasoner
        knowledgeBaseId:
          type: string
        knowledgeInteractionId:
          type: string
        exchangeStart:
          type: string
          format: date-time
        exchangeEnd:
          type: string
          format: date-time
        status:
          type: string
        failedMessage:
          type: string
        argumentBindingSet:
          type: array
          items:
            type: object
            additionalProperties:
              type: string
        resultBindingSet:
          type: array
          items:
            type: object
            additionalProperties:
              type: string       
    KnowledgeInteraction:
      type: object
      required: [knowledgeInteractionType]
      discriminator:
        propertyName: knowledgeInteractionType
        mapping:
          AskKnowledgeInteraction: '#/components/schemas/AskKnowledgeInteraction'
          AnswerKnowledgeInteraction: '#/components/schemas/AnswerKnowledgeInteraction'
          PostKnowledgeInteraction: '#/components/schemas/PostKnowledgeInteraction'
          ReactKnowledgeInteraction: '#/components/schemas/ReactKnowledgeInteraction'
      properties:
        knowledgeInteractionType:
          type: string
        knowledgeInteractionName:
          type: string
          pattern: '^[a-zA-Z0-9-]*$'
        communicativeAct:
          $ref: '#/components/schemas/CommunicativeAct'
        prefixes:
          $ref: '#/components/schemas/Prefixes'
    KnowledgeInteractionId:
      type: object
      properties:
        knowledgeInteractionId:
          type: string
    AskKnowledgeInteraction:
      required: [graphPattern]
      allOf:
        - $ref: '#/components/schemas/KnowledgeInteraction'
        - type: object
          properties:
            graphPattern:
              type: string
    AnswerKnowledgeInteraction:
      required: [graphPattern]
      allOf:
        - $ref: '#/components/schemas/KnowledgeInteraction'
        - type: object
          properties:
            graphPattern:
              type: string
    PostKnowledgeInteraction:
      required: [argumentGraphPattern]
      allOf:
        - $ref: '#/components/schemas/KnowledgeInteraction'
        - type: object
          properties:
            argumentGraphPattern:
              type: string
            resultGraphPattern:
              type: string
    ReactKnowledgeInteraction:
      required: [argumentGraphPattern]
      allOf:
        - $ref: '#/components/schemas/KnowledgeInteraction'
        - type: object
          properties:
            argumentGraphPattern:
              type: string
            resultGraphPattern:
              type: string
    PostResult:
      type: object
      properties:
        resultBindingSet:
          type: array
          items:
            type: object
            additionalProperties:
              type: string
        exchangeInfo:
          type: array
          items:
            $ref: '#/components/schemas/PostExchangeInfo'
        
    CommunicativeAct:
      type: object
      properties:
        requiredPurposes:
          type: array
          items:
            type: string
        satisfiedPurposes:
          type: array
          items:
            type: string
    RegisterKnowledgeInteractionPostReact:
      type: object
      properties:
        knowledgeInteractionType:
          type: string
        communicativeAct:
          $ref: '#/components/schemas/CommunicativeAct'
        argumentGraphPattern:
          type: string
        resultGraphPattern:
          type: string
        prefixes:
          $ref: '#/components/schemas/Prefixes'
    RegisterKnowledgeInteractionAskAnswer:
      type: object
      properties:
        knowledgeInteractionType:
          type: string
        communicativeAct:
          $ref: '#/components/schemas/CommunicativeAct'
        graphPattern:
          type: string
        prefixes:
          $ref: '#/components/schemas/Prefixes'
    BindingSet:
      type: array
      items:
        nullable: false # Enforced manually, but kept here nonetheles.
        type: object
        additionalProperties:
          type: string   
    HandleRequest:
      type: object
      properties:
        knowledgeInteractionId:
          type: string
        handleRequestId:
          type: integer
        bindingSet:
          $ref: '#/components/schemas/BindingSet'
        requestingKnowledgeBaseId:
          type: string
    HandleResponse:
      type: object
      properties:
        handleRequestId:
          type: integer
        bindingSet:
          $ref: '#/components/schemas/BindingSet'
    CreateSmartConnector:
      type: object
      required: [knowledgeBaseId, knowledgeBaseName, knowledgeBaseDescription]
      properties:
        knowledgeBaseId:
          type: string
        knowledgeBaseName:
          type: string
        knowledgeBaseDescription:
          type: string
        leaseRenewalTime:
          type: integer
          minimum: 30
          maximum: 3600
          description: Include this property if you want to have your knowledge
            base automatically unregistered when you don't renew your lease. Expiry
            is checked periodically, so your knowledge base may actually be
            valid for longer than the given time.
        reasonerEnabled:
          type: boolean
          description: Include this optional property if you want to specify whether 
            the smart connector should use a reasoner or a matcher to orchestrate data 
            exchange. In general the reasoner increases the flexibility, but decreases 
            the performance. The matcher decreases the flexibility, but increases 
            the performance.
    AskExchangeInfo:
      type: object
      properties:
        initiator:
          type: string
          enum:
            - knowledgeBase
            - reasoner
        knowledgeBaseId:
          type: string
        knowledgeInteractionId:
          type: string
        exchangeStart:
          type: string
          format: date-time
        exchangeEnd:
          type: string
          format: date-time
        status:
          type: string
        failedMessage:
          type: string
        bindingSet:
          type: array
          items:
            type: object
            additionalProperties:
              type: string
    AskResult:
      type: object
      properties:
        bindingSet:
          type: array
          items:
            type: object
            additionalProperties:
              type: string
        exchangeInfo:
          type: array
          items:
            $ref: '#/components/schemas/AskExchangeInfo'
    ConfigResult:
      type: object
      properties:
        localAddress:
          type: string
        keAddress:
          type: string  
    RegisterAdapterResult:
      type: object
      properties:
        adapterID:
          type: string
    RegisterServiceForm:
      type: object
      properties:
        name:
          type: string
        platform:
          type: string
        descripton:
          type: string
        ontology:
          type: string
        ontology_version:
          type: integer
          format: int32
        type:
          type: string
        expirationDate:
          type: string
        url:
          type: string
    LoginForm:
      type: object
      properties:
        email:
          type: string
        password:
          type: string
    RegisterAdapterForm:
      type: object
      properties:
        hash:
          type: string
        language:
          type: string
        transport:
          type: string
        assetID:
          type: string
    ServiceStoreUser:
      type: object
      properties:
        email:
          type: string
        password:
          type: string
        firstname:
          type: string
        lastname:
          type: string
        statusCode:
          type: integer
          format: int32
        status:
          type: string
    Service:
      type: object
      properties:
        serviceID:
          type: integer
          format: int32
        name:
          type: string
        description:
          type: string
        type:
          type: string
        platform:
          type: string
        ontology:
          type: string
        ontologyVersion:
          type: integer
          format: int32
        expirationDate:
          type: string
        fkServiceStore:
          type: integer
          format: int32
        url:
          type: string
        hash:
          type: string
    Adapter:
      type: object
      properties:
        adapterID:
          type: integer
          format: int32
        language:
          type: string
        registerDate:
          type: string
          format: date-time
        transport:
          type: string
        hash:
          type: string
        active:
          type: boolean
    SmartConnectorLease:
      type: object
      properties:
        knowledgeBaseId:
          type: string
        expires:
          type: string
          format: date-time
    Prefixes:
      type: object
      additionalProperties:
        type: string
        pattern: url
      description:
        If you include a Prefixes object when registering a knowledge interaction,
        you are allowed to use those prefixes in the graph pattern(s) that the 
        knowledge interaction contains. Keep in mind that the prefixes can only
        be used in your graph pattern during registration, and not within bindings.
    RDFBindingSet:
      type: string