Structure

Structure

/api/users/

Supported actions and methods:

/api/users/

Methods: GET, POST

Supported fields for creation:

  • usernamestring (Required. 30 characters or fewer. Letters, numbers and @/./+/-/_ characters)
  • full_name – string
  • native_name – string
  • job_title – string
  • emailemail
  • phone_number – string
  • organization – string
  • description – string
  • is_staff – boolean (Designates whether the user can log into this admin site.)
  • is_active – boolean (Designates whether this user should be treated as active. Unselect this instead of deleting accounts.)
  • is_support – boolean (Designates whether the user is a global support user.)
  • token_lifetime – integer (Token lifetime in seconds.)
  • agree_with_policy – boolean (User must agree with the policy to register.)
  • preferred_language – choice('en', 'et')
  • competence – choice()

User list is available to all authenticated users. To get a list, issue authenticated GET request against /api/users/.

User list supports several filters. All filters are set in HTTP query section. Field filters are listed below. All of the filters apart from ?organization are using case insensitive partial matching.

Several custom filters are supported:

  • ?current - filters out user making a request. Useful for getting information about a currently logged in user.
  • ?civil_number=XXX - filters out users with a specified civil number
  • ?is_active=True|False - show only active (non-active) users
  • ?potential - shows users that have common connections to the customers and are potential collaborators. Exclude staff users. Staff users can see all the customers.
  • ?potential_customer=<Customer UUID> - optionally filter potential users by customer UUID
  • ?potential_organization=<organization name> - optionally filter potential unconnected users by their organization name (deprecated, use organization plugin instead)
  • ?organization_claimed - show only users with a non-empty organization (deprecated, use organization plugin instead)

The user can be created either through automated process on login with SAML token, or through a REST call by a user with staff privilege.

Example of a creation request is below.

POST /api/users/ HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Token c84d653b9ec92c6cbac41c706593e66f567a7fa4
Host: example.com

{
    "username": "sample-user",
    "full_name": "full name",
    "native_name": "taisnimi",
    "job_title": "senior cleaning manager",
    "email": "example@example.com",
    "civil_number": "12121212",
    "phone_number": "",
    "description": "",
    "organization": "",
}

NB! Username field is case-insensitive. So “John” and “john” will be treated as the same user.

/api/users/<uuid>/

Methods: GET, PUT, PATCH, DELETE

Supported fields for update:

  • usernamestring (Required. 30 characters or fewer. Letters, numbers and @/./+/-/_ characters)
  • full_name – string
  • native_name – string
  • job_title – string
  • emailemail
  • phone_number – string
  • organization – string
  • description – string
  • is_staff – boolean (Designates whether the user can log into this admin site.)
  • is_active – boolean (Designates whether this user should be treated as active. Unselect this instead of deleting accounts.)
  • is_support – boolean (Designates whether the user is a global support user.)
  • token_lifetime – integer (Token lifetime in seconds.)
  • agree_with_policy – boolean (User must agree with the policy to register.)
  • preferred_language – choice('en', 'et')
  • competence – choice()

User fields can be updated by account owner or user with staff privilege (is_staff=True). Following user fields can be updated:

  • organization (deprecated, use organization plugin instead)
  • full_name
  • native_name
  • job_title
  • phone_number
  • email

Can be done by **PUT**ing a new data to the user URI, i.e. /api/users/<UUID>/ by staff user or account owner. Valid request example (token is user specific):

PUT /api/users/e0c058d06864441fb4f1c40dee5dd4fd/ HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Token c84d653b9ec92c6cbac41c706593e66f567a7fa4
Host: example.com

{
    "email": "example@example.com",
    "organization": "Bells organization",
}

/api/users/<uuid>/approve_organization/

Methods: POST

Deprecated, use organization plugin instead.

/api/users/<uuid>/claim_organization/

Methods: POST

Deprecated, use organization plugin instead.

/api/users/<uuid>/password/

Methods: POST

To change a user password, submit a POST request to the user’s RPC URL, specifying new password by staff user or account owner.

Password is expected to be at least 7 symbols long and contain at least one number and at least one lower or upper case.

Example of a valid request:

POST /api/users/e0c058d06864441fb4f1c40dee5dd4fd/password/ HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Token c84d653b9ec92c6cbac41c706593e66f567a7fa4
Host: example.com

{
    "password": "nQvqHzeP123",
}

/api/users/<uuid>/reject_organization/

Methods: POST

Deprecated, use organization plugin instead.

/api/users/<uuid>/remove_organization/

Methods: POST

Deprecated, use organization plugin instead.

/api/user-counters/

Count number of entities related to current user

{
    "keys": 1,
    "hooks": 1
}

Supported actions and methods:

/api/user-counters/

Methods: GET

Count number of entities related to current user

{
    "keys": 1,
    "hooks": 1
}

/api/stats/

Historical information about creation time of projects and customers.

Supported actions and methods:

/api/stats/creation-time/

Methods: GET

Historical information about creation time of projects and customers. Available request parameters:

  • ?type=type_of_statistics_objects (required. Have to be from the list: ‘customer’, ‘project’)
  • ?from=timestamp (default: now - 30 days, for example: 1415910025)
  • ?to=timestamp (default: now, for example: 1415912625)
  • ?datapoints=how many data points have to be in answer (default: 6)

Answer will be list of datapoints(dictionaries). Each datapoint will contain fields: ‘to’, ‘from’, ‘value’. ‘Value’ - count of objects, that were created between ‘from’ and ‘to’ dates.

Example:

[
    {"to": 471970877, "from": 1, "value": 5},
    {"to": 943941753, "from": 471970877, "value": 0},
    {"to": 1415912629, "from": 943941753, "value": 3}
]

/api/stats/quota/

Methods: GET

Quotas and quotas usage aggregated by projects/customers.

Available request parameters:
  • ?aggregate=aggregate_model_name (default: ‘customer’. Have to be from list: ‘customer’, ‘project’)
  • ?uuid=uuid_of_aggregate_model_object (not required. If this parameter will be defined - result will contain only object with given uuid)
  • ?quota_name - optional list of quota names, for example ram, vcpu, storage

/api/stats/quota/timeline/

Methods: GET

Historical data of quotas and quotas usage aggregated by projects/customers.

Available request parameters:

  • ?from=timestamp (default: now - 1 day, for example: 1415910025)
  • ?to=timestamp (default: now, for example: 1415912625)
  • ?interval (default: day. Has to be from list: hour, day, week, month)
  • ?item=<quota_name>. If this parameter is not defined - endpoint will return data for all items.
  • ?aggregate=aggregate_model_name (default: ‘customer’. Have to be from list: ‘customer’, ‘project’)
  • ?uuid=uuid_of_aggregate_model_object (not required. If this parameter is defined, result will contain only object with given uuid)

Answer will be list of dictionaries with fields, determining time frame. It’s size is equal to interval parameter. Values within each bucket are averaged for each project and then all projects metrics are summarized.

Value fields include:

  • vcpu_limit - virtual CPUs quota
  • vcpu_usage - virtual CPUs usage
  • ram_limit - RAM quota limit, in MiB
  • ram_usage - RAM usage, in MiB
  • storage_limit - volume storage quota limit, in MiB
  • storage_usage - volume storage quota consumption, in MiB

/api/services/

The summary list of all user services.

Supported actions and methods:

/api/services/

Methods: GET

The summary list of all user services. Filter services by type ^^^^^^^^^^^^^^^^^^^^^^^

It is possible to filter services by their types. Example:

/api/services/?service_type=DigitalOcean&service_type=OpenStack

/api/service-settings/

Supported actions and methods:

/api/service-settings/

Methods: GET, POST

Supported fields for creation:

  • namestring
  • backend_url – URL
  • username – string
  • password – string
  • token – string
  • certificate – file
  • customer – link to /api/customers/<uuid>/
  • homepage – URL
  • terms_of_services – URL
  • scope – GenericRelatedField

To get a list of service settings, run GET against /api/service-settings/ as an authenticated user. Only settings owned by this user or shared settings will be listed.

Supported filters are:

  • ?name=<text> - partial matching used for searching
  • ?type=<type> - choices: OpenStack, DigitalOcean, Amazon, JIRA, GitLab, Oracle
  • ?state=<state> - choices: New, Creation Scheduled, Creating, Sync Scheduled, Syncing, In Sync, Erred
  • ?shared=<bool> - allows to filter shared service settings

To update service settings, issue a PUT or PATCH to /api/service-settings/<uuid>/ as a customer owner. You are allowed to change name and credentials only.

Example of a request:

PATCH /api/service-settings/9079705c17d64e6aa0af2e619b0e0702/ HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Token c84d653b9ec92c6cbac41c706593e66f567a7fa4
Host: example.com

{
    "username": "admin",
    "password": "new_secret"
}

/api/service-settings/<uuid>/

Methods: GET, PUT, PATCH, DELETE

Supported fields for update:

  • namestring
  • backend_url – URL
  • username – string
  • password – string
  • token – string
  • certificate – file
  • homepage – URL
  • terms_of_services – URL
  • scope – GenericRelatedField

To update service settings, issue a PUT or PATCH to /api/service-settings/<uuid>/ as a customer owner. You are allowed to change name and credentials only.

Example of a request:

PATCH /api/service-settings/9079705c17d64e6aa0af2e619b0e0702/ HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Token c84d653b9ec92c6cbac41c706593e66f567a7fa4
Host: example.com

{
    "username": "admin",
    "password": "new_secret"
}

/api/service-settings/<uuid>/stats/

Methods: GET

This endpoint returns allocation of resources for current service setting. Answer is service-specific dictionary. Example output for OpenStack:

  • vcpu - maximum number of vCPUs (from hypervisors)
  • vcpu_quota - maximum number of vCPUs(from quotas)
  • vcpu_usage - current number of used vCPUs
  • ram - total size of memory for allocation (from hypervisors)
  • ram_quota - maximum number of memory (from quotas)
  • ram_usage - currently used memory size on all physical hosts
  • storage - total available disk space on all physical hosts (from hypervisors)
  • storage_quota - maximum number of storage (from quotas)
  • storage_usage - currently used storage on all physical hosts
{
‘vcpu’: 10, ‘vcpu_quota’: 7, ‘vcpu_usage’: 5, ‘ram’: 1000, ‘ram_quota’: 700, ‘ram_usage’: 500, ‘storage’: 10000, ‘storage_quota’: 7000, ‘storage_usage’: 5000

}

/api/service-settings/<uuid>/update_certifications/

Methods: POST

/api/service-metadata/

Supported actions and methods:

/api/service-metadata/

Methods: GET

To get a list of supported service types, run GET against /api/service-metadata/ as an authenticated user. Use an endpoint from the returned list in order to create new service.

/api/service-certifications/

Supported actions and methods:

/api/service-certifications/

Methods: GET, POST

Supported fields for creation:

  • namestring
  • description – string
  • link – URL

/api/service-certifications/<uuid>/

Methods: GET, PUT, PATCH, DELETE

Supported fields for update:

  • namestring
  • description – string
  • link – URL

/api/resources/

Use /api/resources/ to get a list of all the resources of any type that a user can see.

Filter and order SummaryQuerySet of resources

Tags ordering. Filtering for complex tags.

Example:
?tag__license-os=centos7 - will filter objects with tag “license-os:centos7”.
Allow to define next parameters in view:
  • tags_filter_db_field - name of tags field in database. Default: tags.
  • tags_filter_request_field - name of tags in request. Default: tag.

Supported actions and methods:

/api/resources/

Methods: GET

Use /api/resources/ to get a list of all the resources of any type that a user can see. To get a list of supported resources’ actions, run OPTIONS against /api/<resource_url>/ as an authenticated user.

It is possible to filter and order by resource-specific fields, but this filters will be applied only to resources that support such filtering. For example it is possible to sort resource by ?o=ram, but SugarCRM crms will ignore this ordering, because they do not support such option.

There are two query argument to select resources by their type.

  • Specify explicitly list of resource types, for example:

    /api/<resource_endpoint>/?resource_type=DigitalOcean.Droplet&resource_type=OpenStack.Instance

  • Specify category, one of vms, apps, private_clouds or storages for example:

    /api/<resource_endpoint>/?category=vms

Resources may have SLA attached to it. Example rendering of SLA:

"sla": {
    "value": 95.0
    "agreed_value": 99.0,
    "period": "2016-03"
}

You may filter or order resources by SLA. Default period is current year and month.

  • Example query for filtering list of resources by actual SLA:

    /api/<resource_endpoint>/?actual_sla=90&period=2016-02

  • Warning! If resource does not have SLA attached to it, it is not included in ordered response. Example query for ordering list of resources by actual SLA:

    /api/<resource_endpoint>/?o=actual_sla&period=2016-02

Service list is displaying current SLAs for each of the items. By default, SLA period is set to the current month. To change the period pass it as a query argument:

  • ?period=YYYY-MM - return a list with SLAs for a given month
  • ?period=YYYY - return a list with SLAs for a given year

In all cases all currently running resources are returned, if SLA for the given period is not known or not present, it will be shown as null in the response.

Resources may have monitoring items attached to it. Example rendering of monitoring items:

"monitoring_items": {
   "application_state": 1
}

You may filter or order resources by monitoring item.

  • Example query for filtering list of resources by installation state:

    /api/<resource_endpoint>/?monitoring__installation_state=1

  • Warning! If resource does not have monitoring item attached to it, it is not included in ordered response. Example query for ordering list of resources by installation state:

    /api/<resource_endpoint>/?o=monitoring__installation_state

Resource may have tags attached to it. Example of tags rendering:

"tags": [
    "license-os:centos7",
    "os-family:linux",
    "license-application:postgresql",
    "support:premium"
]

Tags filtering:

  • ?tag=IaaS - filter by full tag name, using method OR. Can be list.
  • ?rtag=os-family:linux - filter by full tag name, using AND method. Can be list.
  • ?tag__license-os=centos7 - filter by tags with particular prefix.

Tags ordering:

  • ?o=tag__license-os - order by tag with particular prefix. Instances without given tag will not be returned.

/api/resources/count/

Methods: GET

Use /api/resources/ to get a list of all the resources of any type that a user can see. Count resources by type. Example output:

{
    "Amazon.Instance": 0,
    "GitLab.Project": 3,
    "Azure.VirtualMachine": 0,
    "DigitalOcean.Droplet": 0,
    "OpenStack.Instance": 0,
    "GitLab.Group": 8
}

/api/projects/

Supported actions and methods:

/api/projects/

Methods: GET, POST

Supported fields for creation:

  • namestring
  • customerlink to /api/customers/<uuid>/
  • description – string
  • certifications – list of [{}]

To get a list of projects, run GET against /api/projects/ as authenticated user. Here you can also check actual value for project quotas and project usage

Note that a user can only see connected projects:

  • projects that the user owns as a customer
  • projects where user has any role

Supported logic filters:

  • ?can_manage - return a list of projects where current user is manager or a customer owner;
  • ?can_admin - return a list of projects where current user is admin;

A new project can be created by users with staff privilege (is_staff=True) or customer owners. Project resource quota is optional. Example of a valid request:

POST /api/projects/ HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Token c84d653b9ec92c6cbac41c706593e66f567a7fa4
Host: example.com

{
    "name": "Project A",
    "customer": "http://example.com/api/customers/6c9b01c251c24174a6691a1f894fae31/",
}

Deletion of a project is done through sending a DELETE request to the project instance URI. Please note, that if a project has connected instances, deletion request will fail with 409 response code.

Valid request example (token is user specific):

DELETE /api/projects/6c9b01c251c24174a6691a1f894fae31/ HTTP/1.1
Authorization: Token c84d653b9ec92c6cbac41c706593e66f567a7fa4
Host: example.com

/api/projects/<uuid>/

Methods: GET, PUT, PATCH, DELETE

Supported fields for update:

  • namestring
  • customerlink to /api/customers/<uuid>/
  • description – string

Optional field query parameter (can be list) allows to limit what fields are returned. For example, given request /api/projects/<uuid>/?field=uuid&field=name you get response like this:

{
    "uuid": "90bcfe38b0124c9bbdadd617b5d739f5",
    "name": "Default"
}

A new project can be created by users with staff privilege (is_staff=True) or customer owners. Project resource quota is optional. Example of a valid request:

POST /api/projects/ HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Token c84d653b9ec92c6cbac41c706593e66f567a7fa4
Host: example.com

{
    "name": "Project A",
    "customer": "http://example.com/api/customers/6c9b01c251c24174a6691a1f894fae31/",
}

Deletion of a project is done through sending a DELETE request to the project instance URI. Please note, that if a project has connected instances, deletion request will fail with 409 response code.

Valid request example (token is user specific):

DELETE /api/projects/6c9b01c251c24174a6691a1f894fae31/ HTTP/1.1
Authorization: Token c84d653b9ec92c6cbac41c706593e66f567a7fa4
Host: example.com

/api/projects/<uuid>/update_certifications/

Methods: POST

/api/projects/<uuid>/users/

Methods: GET

A list of users connected to the project

/api/projects/<uuid>/counters/

Methods: GET

Count number of entities related to project

{
    "users": 0,
    "alerts": 2,
    "apps": 0,
    "vms": 1,
    "private_clouds": 1,
    "storages": 2,
}

/api/project-permissions/

  • Projects are connected to customers, whereas the project may belong to one customer only, and the customer may have multiple projects.
  • Projects are connected to services, whereas the project may contain multiple services, and the service may belong to multiple projects.
  • Staff members can list all available projects of any customer and create new projects.
  • Customer owners can list all projects that belong to any of the customers they own. Customer owners can also create projects for the customers they own.
  • Project administrators can list all the projects they are administrators in.
  • Project managers can list all the projects they are managers in.

Supported actions and methods:

/api/project-permissions/

Methods: GET, POST

Supported fields for creation:

  • rolechoice('admin', 'manager', 'support')
  • expiration_time – DateTimeField
  • projectlink to /api/projects/<uuid>/
  • userlink to /api/users/<uuid>/
  • Projects are connected to customers, whereas the project may belong to one customer only, and the customer may have multiple projects.
  • Projects are connected to services, whereas the project may contain multiple services, and the service may belong to multiple projects.
  • Staff members can list all available projects of any customer and create new projects.
  • Customer owners can list all projects that belong to any of the customers they own. Customer owners can also create projects for the customers they own.
  • Project administrators can list all the projects they are administrators in.
  • Project managers can list all the projects they are managers in.

Project permissions expresses connection of user to a project. User may have either project manager or system administrator permission in the project. Use /api/project-permissions/ endpoint to maintain project permissions.

Note that project permissions can be viewed and modified only by customer owners and staff users.

To list all visible permissions, run a GET query against a list. Response will contain a list of project users and their brief data.

To add a new user to the project, POST a new relationship to /api/project-permissions/ endpoint specifying project, user and the role of the user (‘admin’ or ‘manager’):

POST /api/project-permissions/ HTTP/1.1
Accept: application/json
Authorization: Token 95a688962bf68678fd4c8cec4d138ddd9493c93b
Host: example.com

{
    "project": "http://example.com/api/projects/6c9b01c251c24174a6691a1f894fae31/",
    "role": "manager",
    "user": "http://example.com/api/users/82cec6c8e0484e0ab1429412fe4194b7/"
}

To remove a user from a project, delete corresponding connection (url field). Successful deletion will return status code 204.

DELETE /api/project-permissions/42/ HTTP/1.1
Authorization: Token 95a688962bf68678fd4c8cec4d138ddd9493c93b
Host: example.com

/api/project-permissions/<pk>/

Methods: GET, PUT, PATCH, DELETE

Supported fields for update:

  • expiration_time – DateTimeField
  • Projects are connected to customers, whereas the project may belong to one customer only, and the customer may have multiple projects.
  • Projects are connected to services, whereas the project may contain multiple services, and the service may belong to multiple projects.
  • Staff members can list all available projects of any customer and create new projects.
  • Customer owners can list all projects that belong to any of the customers they own. Customer owners can also create projects for the customers they own.
  • Project administrators can list all the projects they are administrators in.
  • Project managers can list all the projects they are managers in.

To remove a user from a project, delete corresponding connection (url field). Successful deletion will return status code 204.

DELETE /api/project-permissions/42/ HTTP/1.1
Authorization: Token 95a688962bf68678fd4c8cec4d138ddd9493c93b
Host: example.com

/api/project-permissions-log/

Supported actions and methods:

/api/project-permissions-log/

Methods: GET

/api/project-permissions-log/<pk>/

Methods: GET

/api/keys/

SSH public keys are injected to VM instances during creation, so that holder of corresponding SSH private key can log in to that instance. SSH public keys are connected to user accounts, whereas the key may belong to one user only, and the user may have multiple SSH keys. Users can only access SSH keys connected to their accounts. Staff users can see all the accounts. Project administrators can select what SSH key will be injected into VM instance during instance provisioning.

Supported actions and methods:

/api/keys/

Methods: GET, POST

Supported fields for creation:

  • name – string
  • public_keystring

SSH public keys are injected to VM instances during creation, so that holder of corresponding SSH private key can log in to that instance. SSH public keys are connected to user accounts, whereas the key may belong to one user only, and the user may have multiple SSH keys. Users can only access SSH keys connected to their accounts. Staff users can see all the accounts. Project administrators can select what SSH key will be injected into VM instance during instance provisioning. To get a list of SSH keys, run GET against /api/keys/ as authenticated user.

A new SSH key can be created by any active users. Example of a valid request:

POST /api/keys/ HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Token c84d653b9ec92c6cbac41c706593e66f567a7fa4
Host: example.com

{
    "name": "ssh_public_key1",
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDURXDP5YhOQUYoDuTxJ84DuzqMJYJqJ8+SZT28
                   TtLm5yBDRLKAERqtlbH2gkrQ3US58gd2r8H9jAmQOydfvgwauxuJUE4eDpaMWupqquMYsYLB5f+vVGhdZbbzfc6DTQ2rY
                   dknWoMoArlG7MvRMA/xQ0ye1muTv+mYMipnd7Z+WH0uVArYI9QBpqC/gpZRRIouQ4VIQIVWGoT6M4Kat5ZBXEa9yP+9du
                   D2C05GX3gumoSAVyAcDHn/xgej9pYRXGha4l+LKkFdGwAoXdV1z79EG1+9ns7wXuqMJFHM2KDpxAizV0GkZcojISvDwuh
                   vEAFdOJcqjyyH4FOGYa8usP1 jhon@example.com",
}

/api/keys/<uuid>/

Methods: GET, DELETE

SSH public keys are injected to VM instances during creation, so that holder of corresponding SSH private key can log in to that instance. SSH public keys are connected to user accounts, whereas the key may belong to one user only, and the user may have multiple SSH keys. Users can only access SSH keys connected to their accounts. Staff users can see all the accounts. Project administrators can select what SSH key will be injected into VM instance during instance provisioning.

/api/customers/

Supported actions and methods:

/api/customers/

Methods: GET, POST

Supported fields for creation:

  • namestring
  • native_name – string
  • abbreviation – string
  • contact_details – string
  • agreement_number – integer
  • email – email
  • phone_number – string
  • registration_code – string
  • country – choice('AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AQ', 'AR', 'AS', 'AT', 'AU', 'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE', 'BF', 'BG', 'BH', 'BI', 'BJ', 'BL', 'BM', 'BN', 'BO', 'BQ', 'BR', 'BS', 'BT', 'BV', 'BW', 'BY', 'BZ', 'CA', 'CC', 'CD', 'CF', 'CG', 'CH', 'CI', 'CK', 'CL', 'CM', 'CN', 'CO', 'CR', 'CU', 'CV', 'CW', 'CX', 'CY', 'CZ', 'DE', 'DJ', 'DK', 'DM', 'DO', 'DZ', 'EC', 'EE', 'EG', 'EH', 'ER', 'ES', 'ET', 'FI', 'FJ', 'FK', 'FM', 'FO', 'FR', 'GA', 'GB', 'GD', 'GE', 'GF', 'GG', 'GH', 'GI', 'GL', 'GM', 'GN', 'GP', 'GQ', 'GR', 'GS', 'GT', 'GU', 'GW', 'GY', 'HK', 'HM', 'HN', 'HR', 'HT', 'HU', 'ID', 'IE', 'IL', 'IM', 'IN', 'IO', 'IQ', 'IR', 'IS', 'IT', 'JE', 'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KI', 'KM', 'KN', 'KP', 'KR', 'KW', 'KY', 'KZ', 'LA', 'LB', 'LC', 'LI', 'LK', 'LR', 'LS', 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD', 'ME', 'MF', 'MG', 'MH', 'MK', 'ML', 'MM', 'MN', 'MO', 'MP', 'MQ', 'MR', 'MS', 'MT', 'MU', 'MV', 'MW', 'MX', 'MY', 'MZ', 'NA', 'NC', 'NE', 'NF', 'NG', 'NI', 'NL', 'NO', 'NP', 'NR', 'NU', 'NZ', 'OM', 'PA', 'PE', 'PF', 'PG', 'PH', 'PK', 'PL', 'PM', 'PN', 'PR', 'PS', 'PT', 'PW', 'PY', 'QA', 'RE', 'RO', 'RS', 'RU', 'RW', 'SA', 'SB', 'SC', 'SD', 'SE', 'SG', 'SH', 'SI', 'SJ', 'SK', 'SL', 'SM', 'SN', 'SO', 'SR', 'SS', 'ST', 'SV', 'SX', 'SY', 'SZ', 'TC', 'TD', 'TF', 'TG', 'TH', 'TJ', 'TK', 'TL', 'TM', 'TN', 'TO', 'TR', 'TT', 'TV', 'TW', 'TZ', 'UA', 'UG', 'UM', 'US', 'UY', 'UZ', 'VA', 'VC', 'VE', 'VG', 'VI', 'VN', 'VU', 'WF', 'WS', 'YE', 'YT', 'ZA', 'ZM', 'ZW')
  • vat_code – string (VAT number)
  • is_company – boolean (Is company or private person)

To get a list of customers, run GET against /api/customers/ as authenticated user. Note that a user can only see connected customers:

  • customers that the user owns
  • customers that have a project where user has a role

Staff also can filter customers by user UUID, for example /api/customers/?user_uuid=<UUID> A new customer can only be created by users with staff privilege (is_staff=True). Example of a valid request:

POST /api/customers/ HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Token c84d653b9ec92c6cbac41c706593e66f567a7fa4
Host: example.com

{
    "name": "Customer A",
    "native_name": "Customer A",
    "abbreviation": "CA",
    "contact_details": "Luhamaa 28, 10128 Tallinn",
}

Deletion of a customer is done through sending a DELETE request to the customer instance URI. Please note, that if a customer has connected projects, deletion request will fail with 409 response code.

Valid request example (token is user specific):

DELETE /api/customers/6c9b01c251c24174a6691a1f894fae31/ HTTP/1.1
Authorization: Token c84d653b9ec92c6cbac41c706593e66f567a7fa4
Host: example.com

/api/customers/<uuid>/

Methods: GET, PUT, PATCH, DELETE

Supported fields for update:

  • namestring
  • native_name – string
  • abbreviation – string
  • contact_details – string
  • email – email
  • phone_number – string
  • registration_code – string
  • country – choice('AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AQ', 'AR', 'AS', 'AT', 'AU', 'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE', 'BF', 'BG', 'BH', 'BI', 'BJ', 'BL', 'BM', 'BN', 'BO', 'BQ', 'BR', 'BS', 'BT', 'BV', 'BW', 'BY', 'BZ', 'CA', 'CC', 'CD', 'CF', 'CG', 'CH', 'CI', 'CK', 'CL', 'CM', 'CN', 'CO', 'CR', 'CU', 'CV', 'CW', 'CX', 'CY', 'CZ', 'DE', 'DJ', 'DK', 'DM', 'DO', 'DZ', 'EC', 'EE', 'EG', 'EH', 'ER', 'ES', 'ET', 'FI', 'FJ', 'FK', 'FM', 'FO', 'FR', 'GA', 'GB', 'GD', 'GE', 'GF', 'GG', 'GH', 'GI', 'GL', 'GM', 'GN', 'GP', 'GQ', 'GR', 'GS', 'GT', 'GU', 'GW', 'GY', 'HK', 'HM', 'HN', 'HR', 'HT', 'HU', 'ID', 'IE', 'IL', 'IM', 'IN', 'IO', 'IQ', 'IR', 'IS', 'IT', 'JE', 'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KI', 'KM', 'KN', 'KP', 'KR', 'KW', 'KY', 'KZ', 'LA', 'LB', 'LC', 'LI', 'LK', 'LR', 'LS', 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD', 'ME', 'MF', 'MG', 'MH', 'MK', 'ML', 'MM', 'MN', 'MO', 'MP', 'MQ', 'MR', 'MS', 'MT', 'MU', 'MV', 'MW', 'MX', 'MY', 'MZ', 'NA', 'NC', 'NE', 'NF', 'NG', 'NI', 'NL', 'NO', 'NP', 'NR', 'NU', 'NZ', 'OM', 'PA', 'PE', 'PF', 'PG', 'PH', 'PK', 'PL', 'PM', 'PN', 'PR', 'PS', 'PT', 'PW', 'PY', 'QA', 'RE', 'RO', 'RS', 'RU', 'RW', 'SA', 'SB', 'SC', 'SD', 'SE', 'SG', 'SH', 'SI', 'SJ', 'SK', 'SL', 'SM', 'SN', 'SO', 'SR', 'SS', 'ST', 'SV', 'SX', 'SY', 'SZ', 'TC', 'TD', 'TF', 'TG', 'TH', 'TJ', 'TK', 'TL', 'TM', 'TN', 'TO', 'TR', 'TT', 'TV', 'TW', 'TZ', 'UA', 'UG', 'UM', 'US', 'UY', 'UZ', 'VA', 'VC', 'VE', 'VG', 'VI', 'VN', 'VU', 'WF', 'WS', 'YE', 'YT', 'ZA', 'ZM', 'ZW')
  • vat_code – string (VAT number)
  • is_company – boolean (Is company or private person)

Optional field query parameter (can be list) allows to limit what fields are returned. For example, given request /api/customers/<uuid>/?field=uuid&field=name you get response like this:

{
    "uuid": "90bcfe38b0124c9bbdadd617b5d739f5",
    "name": "Ministry of Bells"
}

A new customer can only be created by users with staff privilege (is_staff=True). Example of a valid request:

POST /api/customers/ HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Token c84d653b9ec92c6cbac41c706593e66f567a7fa4
Host: example.com

{
    "name": "Customer A",
    "native_name": "Customer A",
    "abbreviation": "CA",
    "contact_details": "Luhamaa 28, 10128 Tallinn",
}

Deletion of a customer is done through sending a DELETE request to the customer instance URI. Please note, that if a customer has connected projects, deletion request will fail with 409 response code.

Valid request example (token is user specific):

DELETE /api/customers/6c9b01c251c24174a6691a1f894fae31/ HTTP/1.1
Authorization: Token c84d653b9ec92c6cbac41c706593e66f567a7fa4
Host: example.com

/api/customers/<uuid>/users/

Methods: GET

A list of users connected to the customer.

/api/customers/<uuid>/image/

Methods: GET, PUT, PATCH, DELETE

/api/customers/<uuid>/counters/

Methods: GET

Count number of entities related to customer

{
    "alerts": 12,
    "services": 1,
    "projects": 1,
    "users": 3
}

/api/customer-permissions/

  • Customers are connected to users through roles, whereas user may have role “customer owner”.
  • Each customer may have multiple owners, and each user may own multiple customers.
  • Staff members can list all available customers and create new customers.
  • Customer owners can list all customers they own. Customer owners can also create new customers.
  • Project administrators can list all the customers that own any of the projects they are administrators in.
  • Project managers can list all the customers that own any of the projects they are managers in.

Supported actions and methods:

/api/customer-permissions/

Methods: GET, POST

Supported fields for creation:

  • rolechoice('owner', 'support')
  • expiration_time – DateTimeField
  • customerlink to /api/customers/<uuid>/
  • userlink to /api/users/<uuid>/
  • Customers are connected to users through roles, whereas user may have role “customer owner”.
  • Each customer may have multiple owners, and each user may own multiple customers.
  • Staff members can list all available customers and create new customers.
  • Customer owners can list all customers they own. Customer owners can also create new customers.
  • Project administrators can list all the customers that own any of the projects they are administrators in.
  • Project managers can list all the customers that own any of the projects they are managers in.

Each customer is associated with a group of users that represent customer owners. The link is maintained through api/customer-permissions/ endpoint.

To list all visible links, run a GET query against a list. Response will contain a list of customer owners and their brief data.

To add a new user to the customer, POST a new relationship to customer-permissions endpoint:

POST /api/customer-permissions/ HTTP/1.1
Accept: application/json
Authorization: Token 95a688962bf68678fd4c8cec4d138ddd9493c93b
Host: example.com

{
    "customer": "http://example.com/api/customers/6c9b01c251c24174a6691a1f894fae31/",
    "role": "owner",
    "user": "http://example.com/api/users/82cec6c8e0484e0ab1429412fe4194b7/"
}

/api/customer-permissions/<pk>/

Methods: GET, PUT, PATCH, DELETE

Supported fields for update:

  • expiration_time – DateTimeField
  • Customers are connected to users through roles, whereas user may have role “customer owner”.
  • Each customer may have multiple owners, and each user may own multiple customers.
  • Staff members can list all available customers and create new customers.
  • Customer owners can list all customers they own. Customer owners can also create new customers.
  • Project administrators can list all the customers that own any of the projects they are administrators in.
  • Project managers can list all the customers that own any of the projects they are managers in.

To remove a user from a customer owner group, delete corresponding connection (url field). Successful deletion will return status code 204.

DELETE /api/customer-permissions/71/ HTTP/1.1
Authorization: Token 95a688962bf68678fd4c8cec4d138ddd9493c93b
Host: example.com

/api/customer-permissions-log/

Supported actions and methods:

/api/customer-permissions-log/

Methods: GET

/api/customer-permissions-log/<pk>/

Methods: GET