Skip to main content

Application Creation Guide

Applications are the way to represent projects in nullplatform. They contain scopes, builds, releases and deployments.

Applications belong to namespaces which belong to accounts and organizations.

Creating a New Application​

Creating a new application involves several steps: discovering the namespace, checking metadata requirements, selecting a template, and finally creating the application.

Step 1: Discover the Namespace​

Before creating an application, you need to identify the namespace where it will be created.

API Call:

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

To get all accounts from your organization:

API Call:

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

Step 2: Check Metadata Specification (Optional)​

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

API Call:

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

Response Example:

{
  "results": [
    {
      "entity": "application",
      "metadata": "application",
      "name": "Application",
      "schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "required": ["businessUnit", "pci", "slo", "applicationOwner"],
        "properties": {
          "businessUnit": {
            "type": "string",
            "description": "The business unit responsible for the service",
            "enum": ["Credits", "Payments", "OnBoarding", "KYC", "Money Market"]
          },
          "pci": {
            "type": "string",
            "description": "Whether the service is PCI compliant",
            "enum": ["Yes", "No"]
          },
          "slo": {
            "type": "string",
            "description": "Service Level Objective classification",
            "enum": ["Critical", "High", "Medium", "Low"]
          },
          "applicationOwner": {
            "type": "string",
            "description": "The lead of the application",
            "enum": ["John Doe", "Jane Smith", "Michael Johnson"]
          }
        }
      }
    }
  ]
}

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

Step 3: List Available Templates​

Templates define the technology stack and initial configuration for your application.

API Call:

Method: GET
Endpoint: /template?limit=200&target_nrn=organization=<org_id>:account=<account_id>:namespace=<namespace_id>&global_templates=true

Response Example:

{
  "results": [
    {
      "id": 715874835,
      "name": "Golang 1.17",
      "status": "active",
      "url": "https://github.com/nullplatform/technology-templates-golang",
      "components": [
        {
          "type": "language",
          "id": "google",
          "version": "1.17"
        }
      ],
      "tags": ["golang", "backend"]
    },
    {
      "id": 1220542475,
      "name": "NodeJS + Fastify",
      "status": "active",
      "url": "https://github.com/nullplatform/technology-templates-nodejs-container",
      "components": [
        {
          "type": "language",
          "id": "javascript",
          "version": "es6"
        },
        {
          "type": "framework",
          "id": "fastify",
          "version": "4.6.0"
        }
      ],
      "tags": ["javascript", "fastify", "backend"]
    }
  ]
}

Note: Only templates with "status": "active" can be used to create applications.

Step 4: Create the Application​

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

Without Metadata​

API Call:

Method: POST
Endpoint: /application
Body: '{
  "namespace_id": "463208973",
  "name": "my-new-app",
  "template_id": "1037172878",
  "auto_deploy_on_creation": false
}'

With Metadata​

API Call:

Method: POST
Endpoint: /application
Body: '{
  "namespace_id": "463208973",
  "name": "my-new-app",
  "template_id": "1037172878",
  "auto_deploy_on_creation": false,
  "repository_url": "https://github.com/my-org/<namespace slug>-<application-slug>",

  "metadata": {
    "application": {
      "businessUnit": "OnBoarding",
      "pci": "No",
      "slo": "Critical",
      "applicationOwner": "Sarah Williams"
    }
  }
}'

Important Fields:

  • namespace_id: The namespace where the application will be created (required)
  • name: The name of your application (required)
  • template_id: The ID of the template to use (required)
  • auto_deploy_on_creation: Whether to automatically deploy after creation (default: false)
  • metadata: Optional metadata object matching the schema from Step 2
  • repository_url: The URL of the repository where the application code will be stored, template can contains rules about how the repository should be named.

Importing an Existing Application​

If you have an existing repository, you can import it into nullplatform without using a template.

Import Application​

API Call:

Method: POST
Endpoint: /application
Body: '{
  "namespace_id": "463208973",
  "name": "my-imported-app",
  "repository_url": "https://github.com/my-org/my-app",
  "repository_app_path": "",
  "metadata": {
    "application": {
      "businessUnit": "Payments",
      "pci": "Yes",
      "slo": "Medium",
      "applicationOwner": "David Brown"
    }
  }
}'

Import-Specific Fields:

  • repository_url: The URL of the existing repository (required for import)
  • repository_app_path: The path within the repository where the app code is located (optional, use "" for root)
  • name: The name of your application (required)
  • namespace_id: The namespace where the application will be created (required)
  • metadata: Optional metadata object matching the namespace schema

Note: When importing, you do not provide a template_id since you're bringing your own repository.

Common Workflow Example​

Creating a New Application with Metadata​

  1. List namespaces:

    Method: GET
    Endpoint: /namespace?account_id=95118862

  2. Check metadata requirements:

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

  3. List available templates:

    Method: GET
    Endpoint: /template?limit=200&target_nrn=organization=1255165411:account=95118862:namespace=463208973&global_templates=true

  4. Create the application:

    Method: POST
    Endpoint: /application
    Body: '{
      "namespace_id": "463208973",
      "name": "payment-service",
      "template_id": "1220542475",
      "auto_deploy_on_creation": false,
      "metadata": {
        "application": {
          "businessUnit": "Payments",
          "pci": "Yes",
          "slo": "Critical",
          "applicationOwner": "John Doe"
        }
      }
    }'

Importing an Existing Application​

  1. List namespaces:

    Method: GET
    Endpoint: /namespace?account_id=95118862

  2. Check metadata requirements:

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

  3. Import the application:

    Method: POST
    Endpoint: /application
    Body: '{
      "namespace_id": "463208973",
      "name": "legacy-api",
      "repository_url": "https://github.com/my-org/legacy-api",
      "repository_app_path": "",
      "metadata": {
        "application": {
          "businessUnit": "KYC",
          "pci": "No",
          "slo": "High",
          "applicationOwner": "Jane Smith"
        }
      }
    }'

Important Notes​

  • Application names must be unique within a namespace
  • Template validation: Some templates have naming rules defined in their rules property that validate application names
  • Metadata validation: If a metadata specification exists with required fields, the metadata must be provided and match the schema
  • Auto-deploy: Setting auto_deploy_on_creation to true will trigger an initial deployment after creation
  • Repository access: When importing, ensure the repository URL is accessible to nullplatform
  • Repository path: Use repository_app_path when your application code is in a subdirectory of the repository

Next Steps​

After creating an application:

  1. Configure scopes (environments) for the application
  2. Set up parameters (environment variables and configuration)
  3. Link your CI/CD pipeline to trigger builds
  4. Create your first deployment

See the Application Read guide for how to view and manage your applications.