openapi: 3.0.0
servers:
  - description: NGINX Controller API
    url: 'https://{{CONTROLLER_FQDN}}/api/v1'
info:
  title: Alerts API
  description: >-
    Use the Alerts API to manage the Alert Rule resources and
    retrieve information about the Alerts.
  version: v1
paths:
  /analytics/alerts/rules:
    get:
      tags:
        - Alert Rules
      summary: List all Alert Rules
      operationId: listAlertRules
      x-f5-experimental: true
      description: Returns a list of all the Alert Rule resources.
      responses:
        '200':
          description: >-
            Successfully retrieved a list of all the Alert Rule
            resources.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AlertRule'
        '400':
          description: >-
            Bad input parameter, or possibly a bad URI. Check the
            input for typos and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '500':
          description: >-
            The request cannot be processed because of an internal
            server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    post:
      tags:
        - Alert Rules
      summary: Create an Alert Rule
      description: Creates a new Alert Rule resource.
      operationId: createAlertRule
      x-f5-experimental: true
      requestBody:
        description: Defines the Alert Rule resource to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertRule'
      responses:
        '201':
          description: >-
            Successfully created the specified Alert Rule
            resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertRule'
        '400':
          description: >-
            Bad input parameter, or possibly a bad URI. Check the
            input for typos and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '409':
          description: >-
            The request failed due to a naming conflict with an
            existing resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '500':
          description: >-
            The request cannot be processed because of an internal
            server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
  '/analytics/alerts/rules/{alertRuleName}':
    parameters:
      - name: alertRuleName
        description: Identifies the Alert Rule resource.
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Alert Rules
      summary: Get an Alert Rule
      description: Returns information for the specified Alert Rule.
      operationId: getAlertRule
      x-f5-experimental: true
      responses:
        '200':
          description: >-
            Successfully returned the requested Alert Rule
            resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertRule'
        '400':
          description: >-
            Bad input parameter, or possibly a bad URI. Check the
            input for typos and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '404':
          description: >-
            The resource defined in the URI could not be found.
            Check the URI for errors and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '500':
          description: >-
            The request cannot be processed because of an internal
            server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    put:
      tags:
        - Alert Rules
      summary: Upsert a Alert Rule
      description: >-
        Creates a new Alert Rule or updates an existing Alert Rule
        resource.
      operationId: updateAlertRule
      x-f5-experimental: true
      requestBody:
        description: >-
          Defines the Alert Rule resource to create or the updates
          to make.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertRule'
      responses:
        '200':
          description: >-
            Successfully updated the specified Alert Rule
            resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertRule'
        '201':
          description: >-
            Successfully created the specified Alert Rule
            resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertRule'
        '400':
          description: >-
            Bad input parameter, or possibly a bad URI. Check the
            input for typos and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '500':
          description: >-
            The request cannot be processed because of an internal
            server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    delete:
      tags:
        - Alert Rules
      summary: Delete an Alert Rule
      description: Deletes the specified Alert Rule resource.
      operationId: deleteAlertRule
      x-f5-experimental: true
      responses:
        '204':
          description: >-
            Successfully deleted the specified Alert Rule
            resource.
        '400':
          description: >-
            Bad input parameter, or possibly a bad URI. Check the
            input for typos and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '404':
          description: >-
            The resource defined in the URI could not be found.
            Check the URI for errors and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '500':
          description: >-
            The request cannot be processed because of an internal
            server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
  '/analytics/alerts/rules/{alertRuleName}/alerts':
    parameters:
      - name: alertRuleName
        description: Identifies the Alert Rule resource.
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Alerts
      summary: Get ongoing Alerts
      description: >-
        Returns information about Alerts for the specified Alert
        Rule.
      operationId: getAlerts
      x-f5-experimental: true
      responses:
        '200':
          description: Successfully returned the requested Alerts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Alert'
        '400':
          description: >-
            Bad input parameter, or possibly a bad URI. Check the
            input for typos and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '404':
          description: >-
            The resource defined in the URI could not be found.
            Check the URI for errors and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '500':
          description: >-
            The request cannot be processed because of an internal
            server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
  '/analytics/alerts/rules/{alertRuleName}/alerts/{alertId}':
    parameters:
      - name: alertRuleName
        description: Identifies the Alert Rule resource.
        in: path
        required: true
        schema:
          type: string
      - name: alertId
        description: Identifies the Alert resource.
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      tags:
        - Alerts
      summary: Get Alert
      description: >-
        Returns information about the requested Alert for the
        specified Alert Rule.
      operationId: getAlert
      responses:
        '200':
          description: Successfully returned the requested Alert.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
        '400':
          description: >-
            Bad input parameter, or possibly a bad URI. Check the
            input for typos and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '404':
          description: >-
            The resource defined in the URI could not be found.
            Check the URI for errors and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '500':
          description: >-
            The request cannot be processed because of an internal
            server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
components:
  schemas:
    Alert:
      title: alert
      type: object
      properties:
        uid:
          type: string
          format: uuid
        dimensions:
          type: object
          additionalProperties:
            type: string
        startedTimestamp:
          type: string
          format: date-time
          example: '2019-07-29T09:12:33.001Z'
          description: Timestamp when the Alert started.
        startedValue:
          type: number
          description: Value of the metric that caused the Alert to start.
        lastCheckedTimestamp:
          type: string
          format: date-time
          example: '2019-07-29T09:12:33.001Z'
          description: Timestamp when the Alert was last checked.
        lastCheckedValue:
          type: number
          description: Value of the metric when the Alert was last checked.
      required:
        - uid
        - dimensions
        - startedTimestamp
        - startedValue
        - lastCheckedTimestamp
        - lastCheckedValue
    AlertRuleStatus:
      title: AlertRuleStatus
      type: object
      properties:
        alertsCount:
          type: integer
          description: >-
            Number of times an Alert for the Alert Rule has been
            started since creation.
        status:
          type: string
          enum:
            - ok
            - ongoing
          description: >
            Alert Rule status:

            - `ok`: All the Alerts have expired or have never
            started.

            - `ongoing`: At least one Alert is currently ongoing.
        lastStartedTimestamp:
          type: string
          format: date-time
          example: '2019-07-29T09:12:33.001Z'
          description: >-
            Timestamp when the Alert Rule transfered from 'ok' to
            'ongoing' status.
        lastExpiredTimestamp:
          type: string
          format: date-time
          example: '2019-07-29T09:12:33.001Z'
          description: >-
            Timestamp when the Alert Rule transfered from
            'ongoing' to 'ok' status.
        lastCheckedTimestamp:
          type: string
          format: date-time
          example: '2019-07-29T09:12:33.001Z'
          description: >-
            Timestamp of the last successful check of the Alert
            Rule.
    AlertRule:
      title: AlertRule
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/ResourceMeta'
        userEmail:
          type: string
          format: email
          readOnly: true
          description: Email of the user who created the Alert Rule.
        metric:
          type: string
          description: A valid metric from the catalog.
          example: upstream.network.latency.max
        aggregation:
          type: string
          description: >-
            Aggregation of the metric over the configured period
            of time.
          readOnly: true
        filter:
          type: string
          description: >
            The use of filter parameter limits the metrics data
            samples being taken into account for Alert Rule
            calculation

            to those matching the filter expression.

            Filter parameter syntax works the same as for
            `/analytics/metrics` API.


            - An empty filter parameter indicates that all
            collected data is going to be taken into account for
            Alert Rule calculation

            - `filter=app='myapp' AND (env='prod' or env='dev')`
            indicates that only samples related to desired app/env
            will be taken into account
          example: >-
            ((app!='app1' OR app='app2') AND environment in
            ('dev', 'prod')) AND (tags!='*tag1*' AND
            interface='ens*')
        groupBy:
          type: string
          description: >
            When `groupBy` is provided, alerts will be triggered
            for each distinct group of provided dimension(s).

            GroupBy parameter syntax works the same as for
            `/analytics/metrics` API.
          example: 'app,environment'
        threshold:
          type: number
          description: >-
            Threshold to which the metric value will be compared
            to.
        operator:
          type: string
          enum:
            - ge
            - le
          description: >
            Operator that defines which metric values will trigger
            an alert:


            - `ge`: metric value must be greater than or equal to
            the threshold in order to trigger an alert

            - `le`: metric value must be less than or equal to the
            threshold in order to trigger an alert
        period:
          type: string
          example: 1h
          description: >
            Period from which the metric aggregated value is
            calculated.


            Must be a valid duration - a string starting with a
            number followed by a unit of time (`h`, `m` or `s`).


            24h is the maximum allowed period.
        notificationType:
          description: >-
            Defines how notifications about triggered Alerts will
            be delivered to the user.
          type: string
          enum:
            - email
        emailAddresses:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            format: email
            example: user@example.com
        mute:
          type: boolean
          description: >-
            Indicates if the Alert Rule is muted. (Muted Alert
            Rules will not trigger notifications).
          default: false
        status:
          $ref: '#/components/schemas/AlertRuleStatus'
          readOnly: true
      required:
        - metadata
        - metric
        - threshold
        - operator
        - period
    SelfLinks:
      type: object
      description: >
        The SelfLinks object contains a link from the resource to
        itself.

        This object is used only in responses.
      properties:
        rel:
          type: string
          example: /api/v1/services/environments/prod
          description: >
            `rel` contains the complete path fragment of a URI and
            can be used

            to construct a query to the object.
    ResourceMeta:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          pattern: >-
            ^[^A-Z\s\x00-\x1f\x60\x7f\;\*\"\[\]\{\}\\\/%\?:=&\~\^|#<>]+$
          not:
            type: string
            enum:
              - .
              - ..
          minLength: 1
          maxLength: 1024
          example: resource-name
          description: >
            Resource name is a unique identifier for a resource
            within the context of a namespace.

            Resource names must conform to [RFC 1738 Section
            2.2](https://www.ietf.org/rfc/rfc1738.txt) and have a
            valid syntax for email addresses. The following rules
            are enforced:


            - do not utilize URL encoding;

            - do not include spaces;

            - do not use uppercase characters, for example, 'A-Z';
            extended character sets are supported;

            - do not use the following characters: `"`, `*`, `:`,
            `;`, `/`, `\`, `%`, `?`, `hash`, `=`, `&`, `|`, `~`,
            `^`, `{`, `}`, `[`, `]`, `<`, `>`;

            - cannot start or end with an `@` sign;

            - cannot be only `.` or `..`


            For example: For a collection resource located at


            `https://controller.example.com/api/v1/services/apps/shopping_@1`


            the resource name is "shopping_@1".
        displayName:
          type: string
          example: My Display Name
          description: >
            `displayName` is a user friendly resource name. It can
            be used to define 

            a longer, and less constrained, name for a resource.


            Display names:


            - are optional (defaults to an empty string if no
            value is provided),

            - do not have to be unique, 

            - cannot be assigned by the server.
        description:
          type: string
          example: >-
            This is a sample description string. It provides
            information about the resource.
          description: >
            `description` is a free-form text property. You can
            use it to provide information that helps 

            to identify the resource.


            Descriptions:


            - are optional (defaults to an empty string if no
            value is provided),

            - do not have to be unique, 

            - cannot be assigned by the server.
        kind:
          type: string
          example: <collection>-<object>
          description: >
            Kind is a string representation of an API resource's
            data type.

            It is assigned by the server and cannot be changed. 


            When creating a `kind`, the server uses hyphens to
            connect word segments; 

            singleton and collection item resources are not
            pluralized.
        uid:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: >
            Unique Identifier (UID)


            UID is a unique identifier in time and space for a
            resource. 

            When you create a resource, the server assigns a UID
            to the resource.


            Refer to [IETF RFC
            4122](https://tools.ietf.org/html/rfc4122) for more
            information.
        tags:
          type: array
          items:
            type: string
          example:
            - production_public
            - dev
            - new_app
            - us-west-1
            - emea
          description: >
            You can assign `tags` to a resource as a way to help
            map, scope, 

            and organize resources. 


            The system uses tag selectors to specify selection
            criteria that 

            match resources that have particular tags.
        ref:
          type: string
          example: /services/environments/prod
          description: >
            The `ref` field contains a reference to another NGINX
            Controller resource.
        links:
          $ref: '#/components/schemas/SelfLinks'
        createTime:
          type: string
          format: date-time
          example: '2019-07-29T09:12:33.001Z'
          description: >
            A timestamp that represents the server time when the
            resource was created.


            Create time is not guaranteed to be set in
            "happens-before" order

            across separate operations.


            In JSON format, `create_time` type is encoded as a
            string in the

            [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt).


            For example: 2018-04-01T01:30:15.01Z


            Create Time is assigned by the server and cannot be
            changed.
        updateTime:
          type: string
          format: date-time
          example: '2019-07-29T10:12:33.001Z'
          description: >
            A timestamp that represents the server time when the
            resource was last modified.


            Resources that have never been updated do not have an
            `update_time` stamp.


            The default value for resources that have never been
            updated is the local 

            language-specific equivalent of "null".


            In JSON format, `update_time` type is encoded as a
            string as described in 

            [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt).
    ErrorDetail:
      type: object
      required:
        - description
      properties:
        description:
          type: string
          example: >-
            Error doing <action>: <reason for error>. This can
            lead to <potential consequences>. Try <action> to
            resolve the issue.
          description: >
            A detailed error message returned by the server. 


            These messages contain the following information,
            where applicable:


            - What happened.

            - Why it happened.

            - What the consequences are (if any).

            - Recommended action to take to resolve the issue.
    ErrorModel:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
          example: Error doing <action>.
          description: >
            A human-readable message, in English, that describes
            the error.
        code:
          type: integer
          example: 1234567
          description: >
            A numeric error code that can be used to identify
            errors for support purposes.
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'