$schema: http://support.riverbed.com/apis/service_def/2.2
description: REST API for npm.usernotify service.
id: http://support.riverbed.com/apis/npm.usernotify/3.0
name: npm.usernotify
provider: riverbed
resources:
  delivery_type:
    additionalProperties: false
    description: 'A registered method of delivery, supporting a global configuration
      structure

      '
    links:
      configure:
        method: PUT
        request:
          $ref: '#/resources/delivery_type'
        response:
          $ref: '#/resources/delivery_type'
      get:
        method: GET
        response:
          $ref: '#/resources/delivery_type'
      self:
        path: $/delivery_types/items/{name}
    properties:
      active:
        description: Whether the delivery type is enabled and usable
        readOnly: true
        type: boolean
      enabled:
        description: 'If disabled, subscriptions for this delivery type will be ignored.

          '
        type: boolean
      name:
        readOnly: true
        type: string
      options:
        $ref: '#/types/delivery_options'
    relations:
      instances:
        resource: '#/resources/delivery_types'
    required:
    - name
    - enabled
    type: object
  delivery_type_statuses:
    additionalProperties: false
    description: Statuses of registered delivery types
    links:
      get:
        method: GET
        response:
          $ref: '#/resources/delivery_type_statuses'
      self:
        path: $/delivery_type_statuses
    properties:
      items:
        items:
          properties:
            configured:
              description: Whether the delivery type has been configured
              type: boolean
            enabled:
              description: Whether the delivery type is enabled
              type: boolean
            name:
              description: Name of the delivery type
              type: string
          relations:
            full:
              resource: '#/resources/delivery_type'
              vars:
                name: 0/name
          type: object
        type: array
    type: object
  delivery_types:
    additionalProperties: false
    description: 'List of all registered delivery types

      '
    links:
      check:
        description: 'Check the configuration of a named delivery type. Returns no
          body if successful, or an error if the test failed.

          '
        method: POST
        path: $/delivery_types/check
        request:
          additionalProperties: true
          oneOf:
          - additionalProperties: false
            description: Check arguments for the email delivery type.
            properties:
              delivery_type:
                enum:
                - email
                type: string
              to:
                $ref: '#/types/email_addresses'
            required:
            - delivery_type
            type: object
          type: object
      get:
        method: GET
        response:
          $ref: '#/resources/delivery_types'
      self:
        path: $/delivery_types
    properties:
      items:
        items:
          $ref: '#/resources/delivery_type'
        type: array
    type: object
  local_certificate:
    additionalProperties: false
    description: 'The SSL certificate presented to a remote syslog server with encryption
      enabled

      '
    links:
      generate:
        description: 'Generate a new self-signed certificate and private key. This
          replaces the current certificate.

          '
        method: POST
        path: $/local_certificate/generate
        request:
          $ref: '#/types/distingushed_name'
        response:
          $ref: '#/resources/local_certificate'
      get:
        method: GET
        response:
          $ref: '#/resources/local_certificate'
      import:
        description: Import a new certificate and private key
        method: POST
        path: $/local_certificate/import
        request:
          additionalProperties: false
          description: Import request format
          properties:
            passphrase:
              description: 'Optional passphrase to decrypt private key

                '
              type: string
            pem:
              description: 'Certificate and private key to import, in PEM format

                '
          required:
          - pem
          type: object
        response:
          $ref: '#/resources/local_certificate'
      self:
        path: $/local_certificate
    properties:
      expires_at:
        description: 'Time at which the certificate expires, in Unix epoch seconds

          '
        type: integer
      fingerprint:
        additionalProperties: false
        description: Certificate fingerprint information
        properties:
          algorithm:
            description: 'The algorithm used to calculate the fingerprint

              '
            type: string
          value:
            description: Fingerprint value
            type: string
        required:
        - algorithm
        - value
        type: object
      issuer:
        $ref: '#/types/distingushed_name'
      key:
        additionalProperties: false
        description: Certificate key information
        properties:
          algorithm:
            description: 'The algorithm used to generate the key

              '
            type: string
          size:
            description: 'The size (number of bits) of the key

              '
            type: integer
        required:
        - algorithm
        - size
        type: object
      pem:
        description: The certificate, in PEM format
        type: string
      subject:
        $ref: '#/types/distingushed_name'
      valid_at:
        description: 'Time at which the certificate becomes valid, in Unix epoch seconds

          '
        type: integer
    required:
    - issuer
    - subject
    - valid_at
    - expires_at
    - fingerprint
    - key
    - pem
    type: object
  notification:
    additionalProperties: false
    description: 'Specification of a registered notification type

      '
    links:
      delete:
        method: DELETE
      get:
        method: GET
        response:
          $ref: '#/resources/notification'
      self:
        path: $/notifications/items/{id}
      set:
        method: PUT
        request:
          $ref: '#/resources/notification'
        response:
          $ref: '#/resources/notification'
    properties:
      attributes:
        additionalProperties: true
        description: Dictionary of attribute names to type values which must be one
          of notification_attribute_type
        type: object
      formatters:
        description: The list of formatters to try when formatting this notification
          type.
        items:
          type: string
        type: array
      id:
        type: string
    relations:
      instances:
        resource: '#/resources/notifications'
    required:
    - id
    type: object
  notifications:
    additionalProperties: false
    description: 'List of registered notification types

      '
    links:
      create:
        description: 'This method is no longer supported.

          '
        method: POST
        request:
          $ref: '#/resources/notification'
        response:
          $ref: '#/resources/notification'
      get:
        method: GET
        response:
          $ref: '#/resources/notifications'
      reload:
        description: 'This method is no longer supported.

          '
        method: POST
        path: $/notifications/reload
        request:
          type: 'null'
        response:
          type: 'null'
      self:
        path: $/notifications
    properties:
      items:
        items:
          $ref: '#/resources/notification'
        type: array
    type: object
  recipient:
    additionalProperties: true
    description: 'A recipient groups multiple notification endpoints that should all
      receive notifications for the same events. ''name'' is a human-readable identifier
      for the Recipient, and addresses is a list of ''addressee'' objects listing
      the endpoints to receive the notifications. Creation of a recipient produces
      a unique ''id'' which is used to reference this recipient in other APIs

      '
    links:
      delete:
        method: DELETE
      get:
        method: GET
        response:
          $ref: '#/resources/recipient'
      self:
        path: $/recipients/items/{id}
      set:
        method: PUT
        request:
          $ref: '#/resources/recipient'
        response:
          $ref: '#/resources/recipient'
    properties:
      addressees:
        description: 'List of addressees to deliver notifications to when this recipient
          is notified

          '
        items:
          $ref: '#/types/addressee'
        type: array
      id:
        type: integer
      name:
        type: string
    required:
    - addressees
    type: object
  recipients:
    additionalProperties: true
    description: 'A list of recipient objects

      '
    links:
      create:
        method: POST
        request:
          $ref: '#/resources/recipient'
        response:
          $ref: '#/resources/recipient'
      get:
        method: GET
        response:
          $ref: '#/resources/recipients'
      self:
        path: $/recipients
    properties:
      items:
        items:
          $ref: '#/resources/recipient'
        type: array
    type: object
  recipients_list:
    additionalProperties: false
    description: 'Abbreviated list of recipient names and their ids

      '
    links:
      get:
        method: GET
        response:
          $ref: '#/resources/recipients_list'
      self:
        params:
          with_delivery_types:
            description: 'Filter returned recipients to those having addressees of
              the given delivery_types. Multiple comma-separated delivery types may
              be specified.

              '
            type: string
        path: $/recipients_list
    properties:
      items:
        items:
          additionalProperties: false
          properties:
            id:
              description: Recipient ID
              type: integer
            name:
              description: Recipient name
              type: string
          relations:
            full:
              description: The full recipient information
              resource: '#/resources/recipient'
              vars:
                id: 0/id
          required:
          - id
          - name
          type: object
        type: array
    required:
    - items
    type: object
  subscription:
    additionalProperties: false
    description: 'Records that the recipients in recipient_ids should receive notifications
      for the types of notification named by notification_id. Optional field ''addressees''
      records additional addressees that will also be notified along with these recipients

      '
    links:
      delete:
        method: DELETE
      get:
        method: GET
        response:
          $ref: '#/resources/subscription'
      self:
        path: $/subscriptions/items/{id}
      set:
        method: PUT
        request:
          $ref: '#/resources/subscription'
        response:
          $ref: '#/resources/subscription'
    properties:
      addressees:
        description: 'A list of extra addressees to notify in addition to the recipient_ids.

          '
        items:
          $ref: '#/types/addressee'
        type: array
      filter:
        $ref: '#/types/data_filter'
      id:
        type: integer
      notification_id:
        type: string
      recipient_ids:
        description: 'Optional list of pre-defined recipient IDs.

          '
        items:
          type: integer
        type: array
    relations:
      instances:
        resource: '#/resources/subscriptions'
    required:
    - notification_id
    type: object
  subscriptions:
    additionalProperties: false
    description: 'List of recorded subscriptions

      '
    links:
      bulk_delete:
        method: POST
        path: $/subscriptions/bulk_delete
        request:
          additionalProperties: false
          oneOf:
          - additionalProperties: true
            required:
            - delete_all
            type: object
          - additionalProperties: true
            required:
            - ids
            type: object
          properties:
            delete_all:
              type: boolean
            ids:
              items:
                additionalProperties: false
                properties:
                  notification_id:
                    type: string
                type: object
              type: array
          type: object
        response:
          $ref: '#/resources/subscriptions'
      create:
        method: POST
        request:
          $ref: '#/resources/subscription'
        response:
          $ref: '#/resources/subscription'
      get:
        method: GET
        response:
          $ref: '#/resources/subscriptions'
      self:
        params:
          notification_id:
            description: 'A notification id string to limit results to. This may use
              asterisks (*) as a wildcard to match any substring. Be aware that the
              wildcard can also match dots; use with caution.

              '
            type: string
          recipient_id:
            type: integer
        path: $/subscriptions
    properties:
      items:
        items:
          $ref: '#/resources/subscription'
        type: array
    type: object
title: user notification service
types:
  addressee:
    additionalProperties: true
    description: 'A base object that associates a delivery_type with data needed to
      send notifications to at least one notification endpoint. ''delivery_type''
      defines the type of notification, and other information must be included to
      specify how and where the notification is delivered. Supported ''delivery_types''
      include ''email'', ''snmp'', ''syslog'', ''encrypted_syslog'', and ''servicenow''

      '
    oneOf:
    - additionalProperties: true
      description: Reserved for handling unknown delivery types
      properties:
        delivery_type:
          not:
            enum:
            - syslog
            - snmp
            - email
            - servicenow
            - encrypted_syslog
            type: string
          type: string
      required:
      - delivery_type
      type: object
    - $ref: '#/types/email_addressee'
    - additionalProperties: false
      description: 'Syslog addressee, supporting both the local and unencrypted remote
        syslog endpoints

        '
      properties:
        delivery_type:
          enum:
          - syslog
          type: string
        host:
          description: Hostname or IP of the remote syslog server. Blank for local
            syslog.
          type: string
        port:
          default: 514
          description: Port of the remote syslog server.
          maximum: 65535
          minimum: 0
          type: integer
      required:
      - delivery_type
      type: object
    - $ref: '#/types/encrypted_syslog_addressee'
    - additionalProperties: false
      description: 'ServiceNow addressee (logs notifications to a ServiceNow incident
        table)

        '
      properties:
        baseurl:
          description: Base URL of the ServiceNow instance
          type: string
        delivery_type:
          enum:
          - servicenow
          type: string
        mode:
          default: itsm
          description: ServiceNow integration mode
          enum:
          - itom
          - itsm
          type: string
        new_password:
          description: Password for the specified ServiceNow account
          type: string
        send_tags:
          default: false
          description: Send tags to ServiceNow
          type: boolean
        tags_field:
          default: u_tag
          description: ServiceNow field to receive tags
          type: string
        username:
          description: ServiceNow account with privileges to write to incident table
          type: string
      required:
      - delivery_type
      - baseurl
      - username
      type: object
    - additionalProperties: true
      description: SNMP addressee, supporting SNMP v1, v2c or v3
      oneOf:
      - $ref: '#/types/snmp_v1_v2_addressee'
      - $ref: '#/types/snmp_v3_addressee'
      type: object
    properties:
      delivery_type:
        type: string
    required:
    - delivery_type
    type: object
  data_filter:
    additionalProperties: true
    description: 'A mapping of key names or JSON pointers to literal strings or regexes
      (e.g. ~/.*/) that must match the value of the named attribute

      '
    type: object
  delivery_options:
    additionalProperties: true
    anyOf:
    - additionalProperties: false
      description: 'Email delivery type configuration

        '
      properties:
        from:
          description: 'Address that notification emails will appear to come from

            '
          type: string
        host:
          $merge:
            source:
              $ref: '#/types/host'
            with:
              description: Hostname or IP address of the SMTP server
        new_password:
          default: ''
          description: 'New plaintext password for authenticated SMTP connections

            '
          type: string
        port:
          description: SMTP server port
          maximum: 65535
          minimum: 0
          type: integer
        security:
          description: 'Type of connection security to use when connecting to the
            SMTP server

            '
          enum:
          - NONE
          - SSL
          - STARTTLS
          type: string
        smtp_timeout:
          description: 'How long connections to the SMTP server wait before timing
            out (default: 30 sec)

            '
          minimum: 1
          type: integer
        username:
          default: ''
          description: 'Username for authenticated SMTP connections. No authentication
            is attempted if this is empty (default)

            '
          type: string
      type: object
    - additionalProperties: false
      description: Syslog delivery options (none supported)
      type: object
    - additionalProperties: false
      description: SNMP delivery options (none supported)
      type: object
    description: 'Generic structure to provide global configuration settings to a
      delivery type

      '
    type: object
  distingushed_name:
    additionalProperties: false
    description: Distinguished name information
    properties:
      common_name:
        description: Common name (CN)
        maxLength: 64
        minLength: 0
        type: string
      country:
        description: Country code (C)
        maxLength: 2
        minLength: 0
        type: string
      email:
        description: Email address
        maxLength: 255
        minLength: 0
        type: string
      locality:
        description: Locality (L)
        maxLength: 128
        minLength: 0
        type: string
      organization:
        description: Organization name (O)
        maxLength: 64
        minLength: 0
        type: string
      organizational_unit:
        description: Organization unit name (OU)
        maxLength: 64
        minLength: 0
        type: string
      state:
        description: State or province name (ST)
        maxLength: 128
        minLength: 0
        type: string
    type: object
  email_addressee:
    additionalProperties: false
    description: 'An email addressee. ''delivery_type'' must be "email", and ''to''
      is the destination email address

      '
    properties:
      delivery_type:
        enum:
        - email
        type: string
      to:
        $ref: '#/types/email_addresses'
    required:
    - delivery_type
    - to
    type: object
  email_addresses:
    description: A list of email addresses as strings
    items:
      type: string
    type: array
  encrypted_syslog_addressee:
    additionalProperties: false
    description: Encrypted syslog (RFC5425) addressee
    properties:
      auth_method:
        description: 'Method used to authorize the remote syslog server. If "certificate_validation"
          is specified, there must be a valid certification path from the configured
          certificates to the certificate presented by the remote server. If "certificate_matching"
          is specified, the certificate presented by the remote server must be present
          in the configured certificates.

          '
        enum:
        - certificate_validation
        - certificate_matching
        type: string
      certificates:
        description: 'List of certificates used to authorize the remote server. When
          using certificate validation, these are the trust anchor and any intermediates.
          When using certificate matching, this would be the expected remote server''s
          certificate (typically only one).

          '
        items:
          $ref: '#/types/trusted_certificate'
        type: array
      delivery_type:
        enum:
        - encrypted_syslog
        type: string
      host:
        description: Hostname or IP of the remote syslog server
        type: string
      port:
        default: 6514
        description: Port of the remote syslog server
        maximum: 65535
        minimum: 0
        type: integer
    required:
    - delivery_type
    - host
    - port
    - auth_method
    - certificates
    type: object
  host:
    description: A host or IPv4 or IPv6 address
    type: string
  notification_attribute_type:
    additionalProperties: false
    description: 'Specification of attributes on a notification and their type. Note
      that these roughly correspond to SNMP standard definitions of the given data
      type. Not all delivery mechanisms are able to fully handle some data types.
      Delivery mechanisms are expected to cleanly ignore those attributes they are
      not able to manage.

      '
    properties:
      name:
        type: string
      type:
        enum:
        - OBJECT
        - MAP
        - ARRAY
        - STRING
        - FLOAT
        - BOOLEAN
        - INTEGER
        - UNSIGNED
        - COUNTER
        - GAUGE
        - BINARY
        - NULLOBJ
        - OBJID
        - TIMETICKS
        - IP_ADDRESS
        - NETWORK_ADDRESS
        - BITS
        type: string
    type: object
  snmp_v1_v2_addressee:
    additionalProperties: false
    description: 'Connection information to send a trap/inform to an SNMP v1/v2 endpoint

      '
    properties:
      address:
        type: string
      delivery_type:
        enum:
        - snmp
        type: string
      new_community:
        type: string
      version:
        enum:
        - '1'
        - 2c
        type: string
    required:
    - delivery_type
    - address
    - version
    type: object
  snmp_v3_addressee:
    additionalProperties: true
    description: 'Connection information to send a trap/inform to an SNMP v3 endpoint

      '
    oneOf:
    - additionalProperties: false
      description: SNMP v3 addressee with no privacy or authentication
      properties:
        address:
          type: string
        delivery_type:
          enum:
          - snmp
          type: string
        engine_id:
          default: ''
          type: string
        new_sec_name:
          type: string
        sec_level:
          enum:
          - NoAuthNoPriv
          type: string
        version:
          enum:
          - '3'
          type: string
      required:
      - delivery_type
      - address
      - version
      - sec_level
      type: object
    - additionalProperties: false
      description: SNMP v3 addressee with authentication but no privacy
      properties:
        address:
          type: string
        auth_proto:
          type: string
        delivery_type:
          enum:
          - snmp
          type: string
        engine_id:
          default: ''
          type: string
        new_auth_password:
          type: string
        new_sec_name:
          type: string
        sec_level:
          enum:
          - AuthNoPriv
          type: string
        version:
          enum:
          - '3'
          type: string
      required:
      - delivery_type
      - address
      - version
      - sec_level
      - auth_proto
      type: object
    - additionalProperties: false
      description: SNMP v3 addressee with authentication and privacy
      properties:
        address:
          type: string
        auth_proto:
          type: string
        delivery_type:
          enum:
          - snmp
          type: string
        engine_id:
          default: ''
          type: string
        new_auth_password:
          type: string
        new_priv_password:
          type: string
        new_sec_name:
          type: string
        priv_proto:
          enum:
          - DES
          - AES
          type: string
        sec_level:
          enum:
          - AuthPriv
          type: string
        version:
          enum:
          - '3'
          type: string
      required:
      - delivery_type
      - address
      - version
      - sec_level
      - auth_proto
      - priv_proto
      type: object
    type: object
  trusted_certificate:
    additionalProperties: false
    description: A certificate or CA-certificate to be trusted
    properties:
      cert_details:
        additionalProperties: false
        description: Certificate details
        properties:
          expires_at:
            description: 'Time at which the certificate expires, in Unix epoch seconds

              '
            type: integer
          fingerprint:
            additionalProperties: false
            description: Certificate fingerprint information
            properties:
              algorithm:
                description: 'The algorithm used to calculate the fingerprint

                  '
                type: string
              value:
                description: Fingerprint value
                type: string
            required:
            - algorithm
            - value
            type: object
          issuer:
            $ref: '#/types/distingushed_name'
          key:
            additionalProperties: false
            description: Certificate key information
            properties:
              algorithm:
                description: 'The algorithm used to generate the key

                  '
                type: string
              size:
                description: 'The size (number of bits) of the key

                  '
                type: integer
            required:
            - algorithm
            - size
            type: object
          subject:
            $ref: '#/types/distingushed_name'
          valid_at:
            description: 'Time at which the certificate becomes valid, in Unix epoch
              seconds

              '
            type: integer
        readOnly: true
        required:
        - issuer
        - subject
        - valid_at
        - expires_at
        - fingerprint
        - key
        type: object
      name:
        description: Name of this certificate
        type: string
      pem:
        description: The certificate, in PEM format
        type: string
    required:
    - name
    - pem
    type: object
version: '3.0'
