openapi: 3.0.0
info:
  description: Aura configuration suggestions API definition.
  version: 10.0.0-main-tv-suggestions-29453.0
  title: Aura configuration suggestions API Swagger
  contact:
    email: auradev@tid.es
servers:
  - url: https://localhost:8999
paths:
  /aura-services/v1/configuration/suggestions/{suggestionId}:
    get:
      tags:
        - Suggestions
      summary: Gets all the info associated to one suggestion
      description: Returns channel info by suggestionId
      operationId: getSuggestionById
      security:
        - apiKeyHeader: []
      parameters:
        - name: suggestionId
          in: path
          description: Unique Aura suggestion identifier
          required: true
          schema:
            type: string
        - name: excludeFields
          description: Filters to exclude some keys from the returned object. Only root values of suggestionConfiguration can be filtered
          in: query
          required: false
          schema:
            type: string
        - name: includeFields
          description: Set all the keys returned in the result object. Only root values of suggestionConfiguration can be filtered
          in: query
          required: false
          schema:
            type: string
        - name: correlator
          in: header
          description:
            Unique identifier of a request to be used as correlator in all
            systems
          required: false
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Successfully retrieved
          headers:
            correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuggestionConfigurationPartial"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
      x-swagger-router-controller: "modules"
    put:
      tags:
        - Suggestions
      summary: Updates all the info associated to one suggestion
      description: Updates all suggestion info
      operationId: updateSuggestion
      security:
        - apiKeyHeader: []
      parameters:
        - name: suggestionId
          in: path
          description: Unique Aura suggestion identifier
          required: true
          schema:
            type: string
        - name: correlator
          in: header
          description:
            Unique identifier of a request to be used as correlator in all systems
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        description: Input suggestionData to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SuggestionConfiguration"
      responses:
        "204":
          description: Successfully updated
          headers:
            correlator:
              description: Correlation id for the different services
              schema:
                type: string
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
      x-swagger-router-controller: "modules"
    patch:
      tags:
        - Suggestions
      summary: Updates some info associated to one suggestion
      description: Updates some fields of suggestion info
      operationId: modifySuggestion
      security:
        - apiKeyHeader: []
      parameters:
        - name: suggestionId
          in: path
          description: Unique Aura suggestion identifier
          required: true
          schema:
            type: string
        - name: correlator
          in: header
          description:
            Unique identifier of a request to be used as correlator in all
            systems
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        description: Input channelData to add
        required: true
        content:
          application/json:
            schema:              
              $ref: "#/components/schemas/SuggestionConfigurationPartial"
      responses:
        "204":
          description: Successfully updated
          headers:
            correlator:
              description: Correlation id for the different services
              schema:
                type: string
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
      x-swagger-router-controller: "modules"
    delete:
      tags:
        - Suggestions
      summary: Delete one suggestion
      description: Delete suggestion info by id
      operationId: deleteSuggestionById
      security:
        - apiKeyHeader: []
      parameters:
        - name: suggestionId
          in: path
          description: Unique Aura suggestion identifier
          required: true
          schema:
            type: string
        - name: correlator
          in: header
          description:
            Unique identifier of a request to be used as correlator in all
            systems
          required: false
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Successfully updated
          headers:
            correlator:
              description: Correlation id for the different services
              schema:
                type: string
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
      x-swagger-router-controller: "modules"
  /aura-services/v1/configuration/suggestions:
    get:
      tags:
        - Suggestions
      summary: Gets all Suggestions info
      description: Returns suggestion info
      operationId: getAllSuggestions
      security:
        - apiKeyHeader: []
      parameters:
        - name: excludeFields
          description: Filters to exclude some keys from the returned object. Only root values of suggestionConfiguration can be filtered
          in: query
          required: false
          schema:
            type: string
        - name: includeFields
          description: Set all the keys returned in the result object. Properties of private properties can't be filtered
          in: query
          required: false
          schema:
            type: string
        - name: correlator
          in: header
          description:
            Unique identifier of a request to be used as correlator in all
            systems
          required: false
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Successfully retrieved
          headers:
            correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SuggestionConfigurationPartial"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-swagger-router-controller: "modules"
    post:
      tags:
        - Suggestions
      summary: Adds a new suggestion
      description: Adds a new complete suggestionId
      operationId: addSuggestion
      security:
        - apiKeyHeader: []
      parameters:
        - name: correlator
          in: header
          description:
            Unique identifier of a request to be used as correlator in all
            systems
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        description: Input suggestionData to add
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SuggestionConfiguration"
      responses:
        "201":
          description: Successfully gathered
          headers:
            correlator:
              description: Correlation id for the different services
              schema:
                type: string
            location:
              description: URI to access this channel configuration
              schema:
                type: string
                format: url
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
        "500":
          $ref: "#/components/responses/InternalError"
      x-swagger-router-controller: "modules"
  /aura-services/v1/configuration/changes/suggestion:
    get:
      tags:
        - Suggestions
      summary: Gets if suggestions have been modified
      description: Returns if suggestions are modified
      operationId: getChangedSuggestions
      security:
        - apiKeyHeader: []
      parameters:
        - name: since
          description: Date to check modifications in extended iso format ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ)
          in: query
          required: true
          schema:
            type: string
        - name: correlator
          in: header
          description: Unique identifier of a request to be used as correlator in all systems
          required: false
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved
          headers:
            correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModificationResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-swagger-router-controller: modules
components:
  responses:
    InvalidRequest:
      description: Incoming HTTP request format is not valid
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
    Unauthorized:
      description: Incoming HTTP request authorization is not valid
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
    Conflict:
      description:
        The request could not be completed due to a conflict with the current
        state of the target resource.
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
    TooManyRequests:
      description: The user has sent too many requests in a given amount of time
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
    InternalError:
      description: Unexpected internal error
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
    NotFound:
      description: Request resource not found
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      name: Authorization
      in: header
  schemas:
    SuggestionEntityModel:
      type: object
      required:
        - entity
        - type
      additionalProperties: false
      properties:
        canon:
          type: string
          description: The canonical form of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.
        entity:
          type: string
          description: The value of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.
        label:
          type: string
          description: The internally used descriptive tag of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.
        score:
          type: number
          description: The accuracy (in per 1 units) of the recognized entity sent on behalf of the Telefónica client interacting with the Aura bot instance. In the case of Aura commands this value should be 1 since in this case fully recognized intentions are sent.
        type:
          type: string
          description: The type of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.
    SuggestionResourceModel:
        type: object
        additionalProperties: false
        properties:
          name:
            type: string
            description: The name of the resource.
          params:
            type: object
            additionalProperties:
              type: string
              description: The parameters of the resource used to complete the text of the resource..
          type:
            type: string
            description: The type of the resource.
    SuggestionConfigurationPartial:
      type: object
      required:
        - id
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: Contains the UUID that identifies the suggestion univocally in Aura.
        name:
          type: string
          description: The name of suggestion
        intent:
          type: string
          description: The Aura intention reference which will determine the Aura dialog to execute.
        entities:
          type: array
          description: The array of additional information the Aura bot instance needs to properly accomplish the intent of the suggestion.
          items:
            $ref: "#/components/schemas/SuggestionEntityModel"
        resources:
          type: array
          description: The array of additional information the Aura bot instance needs to properly accomplish the text of the suggestion.
          items:
            $ref: "#/components/schemas/SuggestionResourceModel"
        metadata:
          $ref: "#/components/schemas/DocumentMetadata"
    SuggestionConfiguration:
      type: object
      allOf:
        - $ref: '#/components/schemas/SuggestionConfigurationPartial'
        - required:
            - id
            - name
            - intent
    DocumentMetadata:
      type: object
      description: Metadata for configuration-api docs
      properties:
        version:
          type: string
          description: configuration-api version when document was created
        createdAt:
          type: string
          description: creation date
          format: date-time
        updatedAt:
          type: string
          description: Date when the content was updated
          format: date-time
      additionalProperties: true
