$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:
        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:
          enum: [MD5, SHA]
          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:
          enum: [MD5, SHA]
          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'