Domains

A domain represent the concept that allow to the users manage organizations and the devices of that organizations

Domain object structure

Table 1. domain objects and attributes
Object / attribute	Description
name	Name of the Domain. This field is mandatory
description	Description of the domain. This field is optional
parentDomain	Domain with upper hierarchy. This field is optional. If this field is not filled the new domain is assigned to the user creator domain

Creating a Domain

POST /north/v80/provision/domains

New domains can be created by sending a POST request using the URL above, including a correctly formatted JSON document in the POST body.

Domain as JSON object

{
  "domain": {
    "name": "Domain_2",
    "description": "Domain description",
    "parentDomain": "Domain_1"
  }
}

This is the request using curl:

curl --request POST \
     --data-binary @domain.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/north/v80/provision/domains \
     -H "Content-type: application/json"

In the response we should see a status code of 201 (created) and a location header which tells us the location (including the assigned identifier) of the newly created domain. Let’s look the response.

HTTP/1.1 201 Created
Location: http://[your_opengate_address]/north/v80/provision/domain/Domain_2

When you create a domain, automatically is created all the plans associated to the parent domain with the check "defaultAssigned" true

Reading a Domain

It is possible to obtain the domains tree through hierarchy parameter. This parameter is boolean, if the value is true, the response contains the domains tree, else only domain.

By default the value of hierarchy parameter is false

GET /north/v80/provision/domains/{domain_name}

You can apply for the domain sending a GET request using the URLs above. You must replace {domain_name} with the name of the domain you want to retrieve. This is the request using curl without hierarchy parameter:

curl --request GET \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/north/v80/provision/domains/Domain_2

The response body could be something like this:

Read a Domain as JSON document (without parameter hierarchy or hierarchy=false)

{
  "domain": {
    "name": "Domain_2",
    "description": "Domain description",
    "parentDomain": "Domain_1"
  }
}

GET /north/v80/provision/domains/{domain_name}?hierarchy=true

You can apply for the domains tree sending a GET request using the hierarchy parameter. You must replace {domain_name} with the name of the parent domain you want to retrieve.

By default if the parameter hierarchy is missing the behavior is the same than the value is hierarchy=false

This is the request using curl with hierarchy parameter:

curl --request GET \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/north/v80/provision/domains/Domain_2?hierarchy=true

Read a Domain as JSON document (with parameter hierarchy or hierarchy=true)

{
  "domain": {
    "name": "Domain_2",
    "description": "Domain description",
    "parentDomain": "Domain_1",
    "domains": [
      {
        "name": "Domain_2_1",
        "description": "Domain description",
        "parentDomain": "Domain_2",
        "domains": [
          {
            "name": "Domain_2_1_1",
            "description": "Domain description",
            "parentDomain": "Domain_2_1"
          }
        ]
      }
    ]
  }
}

Updating a Domain

PUT /north/v80/provision/domains/{domain_name}

Existing domains can be updated by sending a PUT request using the URL above, including a correctly formatted JSON document in the PUT body.

The domain name field can’t be updated

Update a Domain as JSON object

{
    "domain": {
        "description": "Domain description",
        "parentDomain": "Domain_1"
    }
}

This is the request using curl:

curl --request PUT \
     --data-binary @domain.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/north/v80/provision/domains/{domain_name} \
     -H "Content-type: application/json"

Deleting a Domain

DELETE /north/v80/provision/domains/{domain_name}

You can delete domains by sending a DELETE request using the URL above. You must replace {domain_name} with the name of the domain you want to delete. This is the request using curl.

curl --request DELETE \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/north/v80/provision/domains/domain_2