Current State

At the moment contacts can only be configured by using the UI. Contactgroups cannot be configured at all. (see #174)

Problem

We can safely assume that consumers already have their users and usergroups defined somewhere. Maintaining them again for Icinga Notifications shouldn't be necessary.

Solution

We should provide a way to automate their creation. The easiest way is to provide a basic HTTP API to do so:

Authorization

The API must require the notifications/api/v1 permission.

Endpoints

Users: notifications/api/v1/contacts[/<identifier> | ?<filter>]
Groups: notifications/api/v1/contactgroups[/<identifier> | ?<filter>]

Parameters

identifier
This is a UUID. For resources created in the UI, this is a UUIDv4.

filter
A usual filter query string

Request Body Validity

• A request's body is, if accepted, always expected to be JSON. Since it always describes a single resource, a JSON object. No envelope structure is required. The object is the resource definition itself
• Every key not followed by a question mark (?) is mandatory
• The default channel of a user must be an existing channel's name (created manually in the UI)
• Referenced resources (contact -> groups, group -> contacts) must already exist

Resource Structure (Request and Response)

Contact

{
    id: identifier,
    full_name: string,
    username?: string,
    default_channel: string,
    groups?: identifier[],
    addresses?: {}
}

Contactgroup

{
    id: identifier,
    name: string,
    users?: identifier[]
}

Methods

GET

• If a filter is passed
  • Respond with a HTTP 200 code and a list of resources, even if empty
• If no filter and no identifier is passed
  • Respond with a HTTP 200 code and a full list of resources, even if empty
• If an identifier is passed
  • Respond with a HTTP 200 code and the resource, if it exists
  • Respond with a HTTP 404 code, if it does not exist

POST

• If a filter or an invalid request body is passed
  • Respond with a HTTP 400 code
• If an identifier is passed
  • Respond with a HTTP 404 code if the resource is not found
  • Respond with a HTTP 422 code if the resource already exists and is not replaced (id in the body is equal)
  • Respond with a HTTP 201 code if the resource is replaced and include the resulting resource endpoint (with new identifier) in the Location header
• If no identifier is passed
  • Respond with a HTTP 422 code if the resource already exists
  • else, respond with a HTTP 201 code, create the resource and include the resulting resource endpoint (with identifier) in the Location header

PUT

• If no identifier or an invalid request body is passed (different id in the body is invalid)
  • Respond with a HTTP 400 code
• If a valid request body is passed
  • Respond with a HTTP 201 code, if the resource is created
  • Respond with a HTTP 204 code, if the resource is updated

DELETE

• If no identifier is passed
  • Respond with a HTTP 400 code
• If the resource is not found
  • Respond with a HTTP 404 code
• If the resource exists
  • Respond with a HTTP 204 code and remove it

Schema Changes

• Add column external_uuid to contact and contactgroup icinga-notifications#192

Implementation Requirements

• A single controller for each endpoint
  • Don't rely on other parts of this project (e.g. forms)
  • Straight forward code, no unnecessary optimizations or modularisation attempts
  • Quick, but not dirty
• Bypass the ORM, exclusively utilize ipl-sql
  • Implement GET ?filter responses like https://github.com/Icinga/icingadb-web/blob/v1.1.2/library/Icingadb/Data/JsonResultSetUtils.php#L70-L100 and disable PHP's output buffering