Dimensions and values

What are dimensions and dimension values

Dimensions are a user-defined key-value tagging that can be attached to different nullplatform resources (in particular to scopes) and are used to declaring the semantics of what you're creating in business terms (ie: saying "this is a production resource" or "this is a testing resource").

For example, a scope can have the dimension environment with dimension values such as testing or production.

What are the benefits of using dimensions

Let's start with an example. If you associate the DB_PASSWORD parameter to a testing scope, whenever you need to create another testing scope, you will have to ask for the password again and create a new parameter value for that scope. If you're labeling the scope's environment dimension as testing , you just need to set the parameter once for the testing dimension and any scope that's labeled as testing will receive it. This is an example on how dimensions are a way of declaring the semantics of what we're creating.

The same thing happens with approvals, if you want to declare that everything that's production will require an approval, then you'll set the approval action for the right dimension (let's say it's again environment and the dimension value is production) and it will instantly apply to all scopes labeled that way.

Which entities support dimensions

At this time the entities that have notion of dimensions, either to label resources or to act based on dimensions are:

Scopes
Parameters
Runtime Configurations
Approvals
Services

Creating dimensions and values

Dimensions are user-defined. This means that we do not bundle nullplatform with a predefined set of dimensions and it's completely up to you to set them. While our examples are a lot about environments, it's very common to create dimensions for other criteria such as the country or geography where the business operates.

Be careful of adding many dimensions. All dimensions that you create will have to be selected by developers whenever they create a resource such as a scope and this can hurt developer experience. Be mindful of creating dimensions that are useful for your business needs.

Dimension and Values are created at a specific NRN. When you create your dimension (eg: environment, country, ...) you have to specify the NRN level at which they will be available (specifying at a certain level automatically makes it available for all of its children). You can make dimension values (eg: development, UK, ...) available at lower levels.

You can have the same dimensions in sibling NRN but never in a parent-children. It's ok to have the environment dimension defined at the NRN organization=1:account=2 and also at organization=1:account=3 but it's not possible to have it defined also at the NRN organization=1:account=2:namespace=3.

You need ops permissions to alter dimensions. Creating, modifying or deleting dimensions can have huge impact on the underlying infrastructure so changing them requires an ops role.

API Examples

While the complete API is published in the API section of this site, these are some example API calls that you might find useful:

Creating a dimension and a value

POST /dimension
{
  "nrn": "organization=1",
  "name": "Environment",
  "order": 1
}

POST /dimension/1/value
{
  "nrn": "organization=1",
  "name": "Development"
}

Getting a dimension or a value

GET /dimension/1
{
  "id": 1,
  "name": "Environment",
  "nrn": "organization=1234",
  "slug": "environment",
  "status": "active",
  "order": 1
}

GET /dimension/value/1
{
  "id": 1,
  "name": "Dev",
  "nrn": "organization=1:account=2:namespace=3",
  "slug": "dev",
  "status": "active"
}

List dimensions that apply AT a certain NRN (scanning parent NRN nodes but not children)

GET /dimension?nrn=organization=1:account=2
{
  "paging": {
    "offset": 0,
    "limit": 30
  },
  "results": [
    {
      "id": 1234,
      "name": "environment",
      "nrn": "organization=1",
      "slug": "environment",
      "status": "active",
      "order": 1,
      "values": [
        {
          "id": 1,
          "name": "testing",
          "slug": "testing",
          "nrn": "organization=1",
          "status": "active",
          "created_at": "2024-03-15T13:26:19.592Z",
          "updated_at": "2024-03-15T13:26:19.592Z"
        },
        {
          "id": 2,
          "name": "production",
          "slug": "production",
          "nrn": "organization=1",
          "status": "active",
          "created_at": "2024-03-15T13:26:19.592Z",
          "updated_at": "2024-03-15T13:26:19.592Z"
        }
      ]
    }
  ]
}

List dimensions that apply AT OR BELOW a certain NRN (scanning children nodes)

GET /dimension?nrn=organization=1:account=*
{
  "paging": {
    "offset": 0,
    "limit": 30
  },
  "results": [
    {
      "id": 1234,
      "name": "environment",
      "nrn": "organization=1:account=2",
      "slug": "environment",
      "status": "active",
      "order": 1,
      "values": [
        {
          "id": 1,
          "name": "testing",
          "slug": "testing",
          "nrn": "organization=1:account=2",
          "status": "active",
          "created_at": "2024-03-15T13:26:19.592Z",
          "updated_at": "2024-03-15T13:26:19.592Z"
        },
        {
          "id": 2,
          "name": "production",
          "slug": "production",
          "nrn": "organization=1:account=2",
          "status": "active",
          "created_at": "2024-03-15T13:26:19.592Z",
          "updated_at": "2024-03-15T13:26:19.592Z"
        }
      ]
    },
     {
      "id": 2345,
      "name": "environment",
      "nrn": "organization=1:account=3",
      "slug": "environment",
      "status": "active",
      "order": 1,
      "values": [
        {
          "id": 1,
          "name": "development",
          "slug": "development",
          "nrn": "organization=1:account=3",
          "status": "active",
          "created_at": "2024-03-15T13:26:19.592Z",
          "updated_at": "2024-03-15T13:26:19.592Z"
        },
        {
          "id": 2,
          "name": "production",
          "slug": "production",
          "nrn": "organization=1:account=3",
          "status": "active",
          "created_at": "2024-03-15T13:26:19.592Z",
          "updated_at": "2024-03-15T13:26:19.592Z"
        }
      ]
    }
  ]
}

List dimension values

The calls are exactly the same that you'll do for dimensions, replacing /dimension for /dimension/value, here are some examples:

GET /dimension/value?nrn=organization=1:account=2
{
  "paging": {
    "offset": 0,
    "limit": 30
  },
  "results": [
    {
      "id": 2345,
      "name": "Dev",
      "nrn": "organization=1:account=2",
      "slug": "dev",
      "status": "active"
    },
    ...
  ]
}

GET /dimension/value?nrn=organization=1:account=*
{
  "paging": {
    "offset": 0,
    "limit": 30
  },
  "results": [
    {
      "id": 2345,
      "name": "Dev",
      "nrn": "organization=1:account=2",
      "slug": "dev",
      "status": "active"
    },
    {
      "id": 2345,
      "name": "Prod",
      "nrn": "organization=1:account=2",
      "slug": "dev",
      "status": "active"
    },
    {
      "id": 2345,
      "name": "Test",
      "nrn": "organization=1:account=3",
      "slug": "dev",
      "status": "active"
    },
    {
      "id": 2345,
      "name": "Production",
      "nrn": "organization=1:account=3",
      "slug": "dev",
      "status": "active"
    },
    ...
  ]
}

What are dimensions and dimension values​

What are the benefits of using dimensions​

Which entities support dimensions​

Creating dimensions and values​

API Examples​

Creating a dimension and a value​

Getting a dimension or a value​

List dimensions that apply AT a certain NRN (scanning parent NRN nodes but not children)​

List dimensions that apply AT OR BELOW a certain NRN (scanning children nodes)​

List dimension values​