perseo-api.yml

openapi: 3.0.0

info:
  title: Perseo
  description: Perseo API
  version: 1.0.0

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

tags:
  - name: notice
    description: Perseo notice
  - name: rule
    description: Perseo rule
  - name: version
    description: Perseo version

paths:

  /notices:
    post:
      tags:
        - notice
      summary: Notify Perseo
      description: Perseo listens in this endpopint, waiting for NGSI notifications
      operationId: newNotification
      parameters:
        - $ref: '#/components/parameters/service'
        - $ref: '#/components/parameters/servicePath'
        - $ref: '#/components/parameters/correlatorID'
      requestBody:
        $ref: '#/components/requestBodies/Notice'
      responses:
        '200':
          $ref: '#/components/responses/NoticeResponse'

  /rules:
    get:
      tags:
        - rule
      summary: List All Rules
      description: Returns complete rule list
      operationId: gelAllRules
      parameters:
        - $ref: '#/components/parameters/service'
        - $ref: '#/components/parameters/servicePath'
        - $ref: '#/components/parameters/correlatorID'
      responses:
        '200':
          $ref: '#/components/responses/Rules'
    post:
      tags:
        - rule
      summary: Add new rule
      description: Add new Rule in Perseo
      operationId: addNewRule
      parameters:
        - $ref: '#/components/parameters/service'
        - $ref: '#/components/parameters/servicePath'
        - $ref: '#/components/parameters/correlatorID'
      requestBody:
        $ref: '#/components/requestBodies/Rule'
      responses:
        '200':
          $ref: '#/components/responses/newRule'


  /rules/{ruleName}:
    get:
      tags:
        - rule
      summary: Get rule named ruleName
      description: returns the rule named ruleName information
      operationId: getRuleByName
      parameters:
        - $ref: '#/components/parameters/service'
        - $ref: '#/components/parameters/servicePath'
        - $ref: '#/components/parameters/correlatorID'
        - in: path
          name: ruleName
          required: true
          description: The rule name
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Rule'

    delete:
      tags:
        - rule
      summary: Delete rule
      description: Delete a Perseo Rule
      operationId: deleteRule
      parameters:
        - $ref: '#/components/parameters/service'
        - $ref: '#/components/parameters/servicePath'
        - $ref: '#/components/parameters/correlatorID'
        - in: path
          name: ruleName
          required: true
          description: The rule name
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/DeletedRule'

  /version:
    get:
      tags:
        - version
      summary: Perseo Version
      description: Returns the perseo version
      operationId: getVersion
      responses:
        '200':
          $ref: '#/components/responses/Version'

  /admin/log:
    get:
      tags:
        - log
      summary: Get Perseo log level
      description: Returns the Perseo log level
      operationId: gelLogLevel
      responses:
        '200':
          $ref: '#/components/responses/LogInfo'
    put:
      tags:
        - log
      summary: Set Perseo log level
      description: Set the Perseo log level
      operationId: changeLogLevel
      parameters:
        - $ref: '#/components/schemas/LogLevel'
      responses:
        '200':
          description: successful operation


components:

  schemas:

    InternalRule:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        text:
          type: string
        action:
          oneOf:
            - $ref: '#/components/schemas/Action'
            - $ref: '#/components/schemas/ActionList'
        subservice:
          type: string
        service:
          type: string
      required:
        - _id
        - name
        - text
        - action
        - subservice
        - service

    LogLevel:
      type: string
      description: Perseo log levels
      enum:
        - FATAL
        - ERROR
        - WARN
        - INFO
        - DEBUG

    Action:
      oneOf:
        - $ref: '#/components/schemas/UpdateAction'
        - $ref: '#/components/schemas/SMSAction'
        - $ref: '#/components/schemas/EmailAction'
        - $ref: '#/components/schemas/HTTPAction'
        - $ref: '#/components/schemas/TwitterAction'
      discriminator:
        propertyName: type
        mapping:
          update: '#/components/schemas/UpdateAction'
          sms: '#/components/schemas/SMSAction'
          email: '#/components/schemas/EmailAction'
          post: '#/components/schemas/HTTPAction'
          twitter: '#/components/schemas/TwitterAction'

    ActionList:
      type: array
      items:
        $ref: '#/components/schemas/Action'

    ActionType:
      type: string
      description: Perseo action types
      enum:
        - update
        - sms
        - email
        - post
        - twitter

    BasicAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ActionType'
        interval:
          type: string
      required:
        - type

    UpdateAction:
      allOf:
        - $ref: '#/components/schemas/BasicAction'
      type: object
      description: Update attribute action
      properties:
        parameters:
          type: object
          description: Send NGSI Update Operation
          properties:
            id:
              type: string
              description: NGSI entity id. Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule.
            attributes:
              type: array
              description: Entity attributes list
              items:
                type: object
                description: Each attribute information
                properties:
                  name:
                    type: string
                    description: Property id
                  type:
                    type: string
                    description: Property type
                  value:
                    type: string
                    description: Property value
              properties:
                to:
                  type: string
              required:
                - to
        template:
          type: string
          description: SMS text template. Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule.
      required:
        - parameters

    SMSAction:
      allOf:
        - $ref: '#/components/schemas/BasicAction'
      type: object
      description: Send SMS action
      properties:
        parameters:
          type: object
          description: SMS parameters
          properties:
            to:
              type: string
              description: Destination phone number
          required:
            - to
        template:
          type: string
          description: SMS text template. Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule.
      required:
        - parameters
        - template

    EmailAction:
      allOf:
        - $ref: '#/components/schemas/BasicAction'
      type: object
      description: Send Email action
      properties:
        parameters:
          type: object
          description: Email parameters
          properties:
            to:
              type: string
              description: Recipients addresses for the e-mail. Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule.
            from:
              type: string
              description: Address who the e-mail came from. Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule.
            subject:
              type: string
              description: Email subject template. Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule.
          required:
            - to
            - from
            - subject
        template:
          type: string
          description: Email text template. Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule.
      required:
        - parameters
        - template

    HTTPAction:
      allOf:
        - $ref: '#/components/schemas/BasicAction'
      type: object
      description: HTTP request action
      properties:
        parameters:
          type: object
          description: Email parameters
          properties:
            to:
              type: string
              description: Recipients addresses for the e-mail. Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule.
            from:
              type: string
              description: Address who the e-mail came from. Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule.
            subject:
              type: string
              description: Email subject template. Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule.
          required:
            - to
            - from
            - subject
        qs:
          type: object
          description: Object with fields and values to build the query string of the URL. Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule.
        template:
          type: string
          description: Request body. Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule.
        json:
          type: object
          description: JSON body. Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule. In this JSON, you can use substitution syntax in the keys and values of the object's fields. If present, it overrides template from action
        headers:
          type: object
          description: HTTP headers.  An object with fields and values for the HTTP header.  Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule. In this JSON, you can use substitution syntax in the keys and values of the object's fields.
      required:
        - parameters
        - template

    TwitterAction:
      allOf:
        - $ref: '#/components/schemas/BasicAction'
      type: object
      description: Twwiter request action
      properties:
        parameters:
          type: object
          description: Twwiter parameters
          properties:
            consumer_key:
              type: string
              description: Twitter API key
              example: xvz1evFS4wEEPTGEFPHBog
            consumer_secret:
              type: string
              description: Twitter API Secret
              example: L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
            access_token_key:
              type: string
              description: Twitter Access token
              example: xvz1evFS4wEEPTGEFPHBog
            access_token_secret:
              type: string
              description: Twitter Access token secret
              example: L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
          required:
            - to
            - from
            - subject
        template:
          type: string
          description: Twitter message. Use string substitution syntax ${fieldName} to reference the fields of the notification/event, including the id or type of the entity that triggers the rule.
      required:
        - parameters

    NewNotice:
      type: object
      description: New Notice for Perseo
      properties:
        subscriptionId:
          type: string
          example: 5b8e65bb3e39542eae0f9e98
        data:
          type: array
          description: List of NGSI notification objects
          items:
            type: object #TODO NGSI entity information
      required:
        - subscriptionId
        - data

    Rule:
      type: object
      description: New Rule for Perseo
      properties:
        name:
          type: string
        text:
          type: string
        action:
          type: array
          items:
            $ref: '#/components/schemas/Action'
      required:
        - name
        - text
        - action

  requestBodies:

    Notice:
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/NewNotice'

    Rule:
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/Rule'

  responses:

    NoticeResponse:
      description: Notice Response
      content:
        'application/json':
          schema:
            type: object
            properties:
              error:
                type: string
                example: null
              data:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: integer
                      example: 200
                required:
                  - code
            required:
              - error
              - data
      headers:
        - $ref: '#/components/parameters/correlatorID'

    Rules:
      description: All Rules
      content:
        'application/json':
          schema:
            type: object
            properties:
              error:
                type: string
                example: null
              data:
                type: array
                items:
                  $ref: '#/components/schemas/InternalRule'
            required:
              - error
              - data
      headers:
        - $ref: '#/components/parameters/correlatorID'

    Rule:
      description: A Rule
      content:
        'application/json':
          schema:
            type: object
            properties:
              error:
                type: string
                example: null
              data:
                $ref: '#/components/schemas/InternalRule'
            required:
              - error
              - data
      headers:
        - $ref: '#/components/parameters/correlatorID'

    newRule:
      description: Rule Added
      content:
        'application/json':
          schema:
            type: object
            properties:
              error:
                type: string
                example: null
              data:
                type: array
                items:
                  type: object # TODO array with booleans, objets, arrays and nulls ¡Allin!
            required:
              - error
              - data
      headers:
        - $ref: '#/components/parameters/correlatorID'

    DeletedRule:
      description: Rule Deleted
      content:
        'application/json':
          schema:
            type: object
            properties:
              error:
                type: string
                example: null
              data:
                type: array
                items:
                  type: object #TODO array with several things {n:1, ok:1}, [{code:200, body: "{\"name\":\"simple_rule@ficodes/demos/preparation/fiwaresummit2\",\"timeLastStateChange\":1536858899353,\"text\":\"context ctxt$ficodes$demos$preparation$fiwaresummit2 select ev.id? as id, ev.NO2? as NO2 from pattern [every ev=iotEvent(cast(cast(NO2?,String),float)>66)]\",\"state\":\"DESTROYED\"}\n"}, null], null
                required:
                  - code
            required:
              - error
              - data
      headers:
        - $ref: '#/components/parameters/correlatorID'

    LogInfo:
      description: Log level Information
      content:
        'application/json':
          schema:
            type: object
            required:
              - level
            properties:
              level:
                $ref: '#/components/schemas/LogLevel'
      headers:
        - $ref: '#/components/parameters/correlatorID'

    Version:
      description: Perseo Version
      content:
        'application/json':
          schema:
            type: object
            properties:
              error:
                type: string
                example: null
              data:
                type: object
                properties:
                  name:
                    type: string
                    example: perseo
                  description:
                    type: string
                    example: IOT CEP front End
                  version:
                    type: string
                    example: 1.6.0-next
            required:
              - error
              - data
      headers:
        - $ref: '#/components/parameters/correlatorID'

  parameters:

    correlatorID:
      name: fiware-correlator
      description: An ID. This header field is taken from the incoming request (or created if not present) and sent to every external system
      in: header
      required: false
      schema:
        type: string
        example: bfd2493c-a7ee-49ef-a932-67b0a0578e43; perseocep=27

    service:
      name: Fiware-Service
      description: Fiware Service
      in: header
      required: false
      schema:
        type: string
        example: serviceExample

    servicePath:
      name: Fiware-ServicePath
      description: Fiware Service path
      in: header
      required: false
      schema:
        type: string
        example: /demo/example/api