Namespace Creation Guide

Namespaces are logical groupings for applications in nullplatform. They help organize applications by team, project, or business unit.

Namespaces belong to accounts which belong to organizations.

Creating a New Namespace

Creating a namespace involves discovering the account, optionally checking metadata requirements, and creating the namespace.

Step 1: Discover the Account

Before creating a namespace, you need to identify the account where it will be created.

API Call:

Method: GET
Endpoint: /account?organization_id=<organization_id>

Step 2: Check Metadata Specification (Optional)

Some accounts require metadata when creating namespaces. To check if metadata is required and what schema to follow:

API Call:

Method: GET
Endpoint: /metadata_specification?entity=namespace&nrn=organization=<org_id>:account=<account_id>&merge=true

Response Example:

{
  "results": [
    {
      "entity": "namespace",
      "metadata": "namespace",
      "name": "Namespace",
      "schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "required": ["team", "costCenter"],
        "properties": {
          "team": {
            "type": "string",
            "description": "The team responsible for this namespace",
            "enum": ["Platform", "Backend", "Frontend", "Data"]
          },
          "costCenter": {
            "type": "string",
            "description": "Cost center for billing purposes",
            "enum": ["CC-001", "CC-002", "CC-003"]
          },
          "owner": {
            "type": "string",
            "description": "The owner of the namespace"
          }
        }
      }
    }
  ]
}

Important: If a metadata specification exists with required fields, you must include the metadata in the namespace creation request.

Step 3: Create the Namespace

Once you have the account and optional metadata, you can create the namespace.

Without Metadata

API Call:

Method: POST
Endpoint: /namespace
Body: '{
  "account_id": "95118862",
  "name": "my-team"
}'

With Metadata

API Call:

Method: POST
Endpoint: /namespace
Body: '{
  "account_id": "95118862",
  "name": "my-team",
  "metadata": {
    "namespace": {
      "team": "Backend",
      "costCenter": "CC-001",
      "owner": "John Doe"
    }
  }
}'

Important Fields:

• account_id: The account where the namespace will be created (required)
• name: The name of your namespace (required)
• metadata: Optional metadata object matching the schema from Step 2

Listing Namespaces

To view all namespaces in an account:

API Call:

Method: GET
Endpoint: /namespace?account_id=<account_id>

Reading a Specific Namespace

To get details about a specific namespace:

API Call:

Method: GET
Endpoint: /namespace/:id

Updating a Namespace

To update a namespace's name or metadata:

API Call:

Method: PATCH
Endpoint: /namespace/:id
Body: '{
  "name": "updated-name",
  "metadata": {
    "namespace": {
      "team": "Platform",
      "costCenter": "CC-002",
      "owner": "Jane Smith"
    }
  }
}'

Common Workflow Example

Creating a Namespace with Metadata

1. List accounts:

   Method: GET
   Endpoint: /account?organization_id=1255165411

2. Check metadata requirements:

   Method: GET
   Endpoint: /metadata_specification?entity=namespace&nrn=organization=1255165411:account=95118862&merge=true

3. Create the namespace:

   Method: POST
   Endpoint: /namespace
   Body: '{
     "account_id": "95118862",
     "name": "backend-team",
     "metadata": {
       "namespace": {
         "team": "Backend",
         "costCenter": "CC-001",
         "owner": "John Doe"
       }
     }
   }'

Creating Multiple Namespaces

1. List accounts:

   Method: GET
   Endpoint: /account?organization_id=1255165411

2. Create first namespace (Backend):

   Method: POST
   Endpoint: /namespace
   Body: '{
     "account_id": "95118862",
     "name": "backend-team"
   }'

3. Create second namespace (Frontend):

   Method: POST
   Endpoint: /namespace
   Body: '{
     "account_id": "95118862",
     "name": "frontend-team"
   }'

4. Create third namespace (Platform):

   Method: POST
   Endpoint: /namespace
   Body: '{
     "account_id": "95118862",
     "name": "platform-team"
   }'

Important Notes

• Namespace names must be unique within an account
• Metadata validation: If a metadata specification exists with required fields, the metadata must be provided and match the schema
• Organization: Namespaces help organize applications by team, project, or business unit
• Naming convention: Use descriptive names that reflect the team or purpose (e.g., "backend-team", "mobile-apps", "data-platform")
• Slug generation: Namespace names are automatically converted to slugs (lowercase with hyphens) for use in URLs and identifiers

Next Steps

After creating a namespace:

1. Create applications within the namespace
2. Set up dimensions (environment types like dev, staging, production)
3. Configure namespace-level policies and permissions
4. Add team members with appropriate access levels

See the Application Create guide for how to create applications within your namespace.