Domain API

The Domain API is used to manage domains. The domains are represented as a tree and the user can be restricted to only see part of the domain tree and that applies to all actions.

LIST

Required role: Read
Required privilege: Domains.READ on the home domain of the calling user

Returns the entire domain tree.

API Endpoint: [GET]: /domains

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query parameters

  • attributes: A comma-separated list with attributes to get: name,description,data or any of the three

Response

The entire domain tree for the user domain will be returned so for the simple case with just a user domain node called DomainA and a sub-domain called sub the following will be the output. Also, will return the domains which are not in user domain but user has READ privilege to them, for example DomainB.

  • DomainA: The id of the user domain.
    • attributes: Every node in the tree has an element called attributes where information about the domain is returned.
      • name The name of the user domain. optional
      • description: A longer description of the user domain. optional
      • data: Custom data about the user domain. optional
    • sub: The id of the new domain.
      • attributes Every node in the tree has an element called attributes where information about the domain is returned.
      • name: The name of the sub domain. optional
      • description: A longer description of the sub domain. optional
      • data: Custom data about the sub domain. optional
  • DomainB: The id of privileged domain.
    • name The name of the privileged domain. optional
    • description: A longer description of the privileged domain. optional
    • data: Custom data about the privileged domain. optional

LIST_TOP_DOMAINS

Required role: Read
Required privilege: Domains.READ on at least one domain

Returns the topmost domains that the current user has access to.

API Endpoint: [GET]: /domains/list

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query parameters

  • size: The wanted page size. (max 100) optional
  • marker: The marker to get the next page. Received in previous response. optional
  • attributes: A comma-delimited string of attributes that should be included in the response. If empty or not set, only the id attribute will be returned. Available attributes: id, name, description, parents, data, domainMetadata, settings.

Response

  • domains: An array containing the topmost domains
    • id: The id of the domain.
    • name: The name of the domain.
    • description: A longer description of the user domain.
    • parents: The domains parents up to the topmost accessible domain.
    • data: Custom data about the domain. Each field in the data object corresponds to a field in domainMetadata so the key is the id from domainMetadata.
    • domainMetadata[]: A list of metadata definitions for the custom data.
      • id: generated id for the field.
      • label: A label describing the field. This is the information that should be shown to the user.
      • type: The type of the field, can be one of text or number.
    • settings: The settings for the domain.
      • theme: The theme settings for the domain.
      • ...

LIST_SUBDOMAINS

Required role: Read
Required privilege: Domains.READ on the specified domain

Returns the subdomains of the domain with the supplied id.

API Endpoint: [GET]: /domains/{id}/list

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Path parameters

  • id: The id of the domain to get subdomains for. required

Query parameters

  • size: The wanted page size. (max 100) optional
  • marker: The marker to get the next page. Received in previous response. optional
  • attributes: A comma-delimited string of attributes that should be included in the response. If empty or not set, only the id attribute will be returned. Available attributes: id, name, description, parents, data, domainMetadata, settings.

Example request

GET: /domains/root/list?size=10&marker=someMarker

Response

  • domains: An array containing the topmost domains
    • id: The id of the domain.
    • name: The name of the domain.
    • description: A longer description of the user domain.
    • parents: The domains parents up to the topmost accessible domain.
    • data: Custom data about the domain. Each field in the data object corresponds to a field in domainMetadata so the key is the id from domainMetadata.
    • domainMetadata[]: A list of metadata definitions for the custom data.
      • id: generated id for the field.
      • label: A label describing the field. This is the information that should be shown to the user.
      • type: The type of the field, can be one of text or number.
    • settings: The settings for the domain.
      • theme: The theme settings for the domain.
      • ...
  • pageInfo: Pagination info
    • itemCount: The number of items on this page.
    • size: The size of the page, i.e. the number of items per page.
    • hasNext: Indicates if there are more pages.
    • marker: The marker that was used for this page.
    • nextMarker: The marker that should be used to get the next page.

CREATE

Required role: ReadWrite
Required privilege: Domains.CREATE on the parent domain specified in the request

Creates a new domain and adds it to the domain tree.

API Endpoint: [POST]: /domains

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query parameters

  • returnDomainTree: A boolean value to indicate if the response should include the resulting domain tree after the operation. Set to false to increase performance of the operation. Defaults to true for backwards compatibility. optional

Body

  • id: The id of the domain to add. Must conform to regex /^[a-zåäöA-ZÅÄÖ0-9_.,-]+$/ required
  • parentId: The id of the parent of the new domain. required
  • name: The name of the domain. required
  • description: A longer description of the domain.
  • data: Custom data about the domain. The data should match the structure defined in domainMetadata, see GET for more information.
  • settings
    • max_users: The maximum amount of users allowed in total on this domain and all subdomains.
    • max_things: The maximum amount of things allowed in total on this domain and all subdomains.
    • max_thingtypes: The maximum amount of thing types allowed in total on this domain and all subdomains.
    • publicUrl: To change the domain’s url used in email templates to your own protocol://host i.e. https://example.com .

Example payload

{
  "id": "sub",
  "parentId": "root",
  "name": "Sub Domain",
  "description": "A sub domain of root",
  "data": {
    "email": "info@sub.root.se"
  },
  "settings": {
      "max_users": 2
  },
  "domainMetadata": [
      {
          "id": "lang",
          "label": "language",
          "type": "text"
      }
  ]
}

Response

If the domain is a subdomain of the user’s home domain and the returnDomainTree query parameter is omitted (or explicitly set to true), the entire domain tree will be returned. For the simple case with just a root node called root the following will be the output.

  • root: The id of the parent of the new domain.
    • attributes: Every node in the tree has an element called attributes where information about the domain is returned.
      • …
    • sub: The id of the new domain.
      • attributes: Every node in the tree has an element called attributes where information about the domain is returned.
        • name: The name of the domain.
        • description: A longer description of the domain.
        • data: Custom data about the domain.
        • settings: The settings of the domain.

Otherwise it will only return the domain which is created.

  • NewDomain: The id of the new domain. required
    • name: The name of the domain. required
    • description: A longer description of the domain.
    • data: Custom data about the domain.
    • settings: The settings of the domain.

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN parentId Returned if the user tries to create a new domain under a domain that the user is not authorized to see.
INVALID_ARGUMENTS id Returned if no id was provided.
INVALID_ARGUMENTS parentId Returned if no parentId was provided.
INVALID_ARGUMENTS name Returned if no name was provided.
DOMAIN_ID_EXISTS id Returned if a domain with the specified id already exists.
DOMAIN_DEPTH_EXCEEDED Returned if the domain tree depth exceeds the maximum allowed depth.

GET

Required role: Read
Required privilege: Domains.READ on the specified domain

Gets information about a domain.

API Endpoint: [GET]: /domains/{id}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Path parameters

  • id: The id of the domain to get, set in query path. required

Query parameters

  • attributes: A comma separated list of attributes to retrieve: (parentId | name | description | data | domainMetadata | thingTypeMetadata | settings)

Response

  • id: The id of the domain.
  • parentId: The id of the parent of the domain.
  • name: The name of the domain.
  • description: A longer description of the domain.
  • data: Custom data about the domain. Each field in the data object corresponds to a field in domainMetadata so the key is the id from domainMetadata.
  • domainMetadata[]: A list of metadata definitions for the custom data.
    • id: generated id for the field.
    • label: A label describing the field. This is the information that should be shown to the user.
    • type: The type of the field, can be one of text or number.
  • settings: The settings for the domain.
    • theme: The theme settings for the domain.
    • ...

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN parentId Returned if the user tries to get a domain that the user is not authorized to see.
PROPERTY_REQUIRED id Returned if no id was provided.
DOMAIN_NOT_FOUND id Returned if the domain cannot be found.

UPDATE

Required role: ReadWrite
Required privilege: Domains.UPDATE on the specified domain

Updates a domain and/or moves it and its sub-domains to a new parent domain. Note, you can not move a domain which is not in user domain. Also, a domain in user domain can not be moved to a domain which is not in user domain.

API Endpoint: [PATCH]: /domains/{id}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Path parameters

  • id: The id of the domain to update/move, set in query path. required

Query parameters

  • returnDomainTree: A boolean value to indicate if the response should include the resulting domain tree after the operation. Set to false to increase performance of the operation. Defaults to true for backwards compatibility. optional

Body

  • parentId: The id of the new parent to move the domain to.
  • name: The new name of the domain.
  • description: The new description of the domain.
  • data: The new custom data about the domain. The data should match the structure defined in domainMetadata, see GET for more information.
  • domainMetadata[]: The new list of metadata definitions for the custom data. The list is replaced so all fields must be provided.
    • id: A generated id for the field.
    • label: A label describing the field.
    • type: The type of the field, can be one of text or number.
  • settings: The new settings for the domain.
    • theme: The new theme setting for the domain.
    • max_users: The maximum amount of users allowed in total on this domain and all subdomains. Set to null to remove limitation.
    • max_things: The maximum amount of things allowed in total on this domain and all subdomains. Set to null to remove limitation.
    • max_thingtypes: The maximum amount of thing types allowed in total on this domain and all subdomains. Set to null to remove limitation.
    • publicUrl: To change the domain’s url used in email templates to your own protocol://host i.e. https://example.com .

Example payload

{
  "parentId": "sub1",
  "name": "Sub Domain 1.1",
  "description": "A sub domain of sub1",
  "data": {
    "email": "info@sub.sub1.root.se"
  },
  "settings": {
      "max_users": 2
  },
  "domainMetadata": [
      {
          "id": "lang",
          "label": "language",
          "type": "text"
      }
  ]
}

Response

If the original domain is the calling user’s home domain (or a subdomain of the user’s home domain) and the returnDomainTree query parameter is omitted (or explicitly set to true), the entire domain tree will be returned. For example, if the domain sub was moved from root to sub1 the following can be the output. Note that the domain tree only includes ids and other updated properties of domains.

  • root: The id of the the old parent.
    • attributes
      • ...
    • sub1: The id of the new parent.
      • attributes
        • ...
      • sub: The id of the domain that was moved.
        • attributes: Every node in the tree has an element called attributes where information about the domain is returned.
          • name: The name of the domain.
          • description: A longer description of the domain.
          • data: Custom data about the domain.
          • domainMetadata[]: list of metadata definitions for the custom data. This is only included if domainMetadata is specified in the input.
          • settings: The settings for the domain. This is only included if settings is specified in the input.

Otherwise, it will return only the updated domain.

  • DomainA: The id of the domain.
    • name: The name of the domain.
    • description: A longer description of the domain. optional
    • data: Custom data about the domain. optional
    • domainMetadata[]: list of metadata definitions for the custom data. This is only included if domainMetadata is specified in the input. optional
    • settings: The settings for the domain. This is only included if settings is specified in the input.

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN id Returned if the user tries to move a domain that the user is not authorized to see.
NOT_AUTHORIZED_DOMAIN parentId Returned if the user tries to move the domain to a domain that the user is not authorized to see.
PROPERTY_REQUIRED id Returned if no id was provided.
DOMAIN_DEPTH_EXCEEDED Returned if the domain tree depth exceeds the maximum allowed depth.

REMOVE

Required role: ReadWrite
Required privilege: Domains.DELETE on a parent of the specified domain

Removes a domain and all of its sub-domains. A domain cannot be removed if there are users, things or thing types associated with the domain or any of its sub-domains. Also, a privileged domain can not be removed if it is not in user domain and has sub-domain.

API Endpoint: [DELETE]: /domains/{id}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Path Parameters

  • id: The id of the domain to remove, set in query path. required

Query parameters

  • returnDomainTree: A boolean value to indicate if the response should include the resulting domain tree after deletion. Set to false to increase performance of the operation. Defaults to true for backwards compatibility. optional

Response

If the removed domain was in the user domain, the entire domain tree, which user has access to, will be returned. So if the domain sub was removed from root and the user has access to root domain, the following would be the output.

  • root:
    • attributes:
      • id: The id of the parent of the removed domain.
      • name: The name of the parent of the removed domain.

Otherwise the response will be empty.

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN id Returned if the user tries to remove a domain that the user is not authorized to see.
PROPERTY_REQUIRED id Returned if no id was provided.
DOMAIN_HAS_THINGS Returned if the domain cannot be removed because it has things attached to it or any of its sub-domains.
DOMAIN_HAS_USERS Returned if the domain cannot be removed because it has users attached to it or any of its sub-domains.
DOMAIN_HAS_THING_TYPES Returned if the domain cannot be removed because it has thing types attached to it or any of its sub-domains.
DOMAIN_NOT_FOUND id Returned if the specified domain id does not exist.