App Config.json Documentation

Comprehensive guide for configuration management, SDK usage, API integration, and best practices.

Introduction

App Config.json is a centralized, zero-downtime configuration management platform designed for modern microservices and monolithic applications. It enables teams to define, version, sync, and deploy configuration across environments using a familiar JSON structure.

💡 Prerequisites

Ensure you have an active account, an API key, and Node.js 18+ (or equivalent runtime for your SDK). All examples use v3.0.0 of the platform.

Installation

Install the official SDK via your preferred package manager:

npm / yarn / pnpm

npm install @appconfig/json-sdk
yarn add @appconfig/json-sdk
pnpm add @appconfig/json-sdk

For other languages (Python, Go, Rust, Java), refer to the Language-Specific SDKs section.

Quick Start

Initialize the client and load your configuration in under 10 lines:

index.js
import { AppConfig } from '@appconfig/json-sdk';

const config = new AppConfig({
  apiKey: 'ac_live_xxxxxxxxxxxx',
  projectId: 'proj_9f8a7b6c',
  environment: 'production',
  autoSync: true
});

// Load & subscribe to live updates
await config.load();
config.subscribe((changes) => {
  console.log('Config updated:', changes);
});

Configuration Schema

All configurations must adhere to the following JSON structure. The platform validates schemas automatically.

config.schema.json
{
  "$schema": "https://appconfig.json/schemas/v3",
  "app": {
    "name": "my-service",
    "version": "1.4.2"
  },
  "features": {
    "enable_cache": true,
    "cache_ttl": 3600,
    "max_retries": 3
  },
  "endpoints": {
    "api": "https://api.example.com/v2",
    "ws": "wss://ws.example.com"
  }
}

Key	Type	Required	Description
`app.name`	string	Yes	Unique identifier for your application
`features.*`	any	No	Feature flags or runtime toggles
`endpoints.*`	string (URL)	No	Service endpoints and URIs
`secrets.*`	string (encrypted)	No	Auto-resolved secrets from vault

Environment Management

App Config.json supports environment-specific overrides without duplicating entire files. Use the extends directive to layer configurations:

staging.config.json
{
  "extends": "base",
  "environment": "staging",
  "overrides": {
    "features.debug": true,
    "endpoints.api": "https://staging-api.example.com/v2"
  }
}

ℹ️ Supported Environments

development, staging, production, custom_*. Environment names are case-sensitive.

SDK Methods & Events

The SDK exposes a promise-based API with real-time event listeners.

Method	Returns	Description
`load()`	Promise<void>	Fetches and caches the latest configuration
`get(path)`	any	Retrieves a value using dot notation (e.g., `features.cache_ttl`)
`subscribe(fn)`	UnsubscribeFn	Registers a listener for live config changes
`rollback(version)`	Promise<void>	Reverts to a specific configuration version
`validate()`	Promise<boolean>	Runs schema validation against current payload

REST API

All SDK operations are backed by a versioned REST API. Base URL: https://api.appconfig.json/v3

GET /projects/{id}/configs
// Headers
Authorization: Bearer <api_key>
Accept: application/json

// Response
{
  "version": 42,
  "timestamp": "2025-04-12T08:30:00Z",
  "data": { ... },
  "checksum": "sha256:8f3d..."
}

Versioning & Rollback

Every configuration push creates an immutable version. You can rollback via SDK or CLI:

CLI

ac rollback --project proj_9f8a7b6c --version 41 --env production
// Output: Successfully rolled back to v41. Instances syncing...

⚠️ Rollback Limits

Free tier supports 10 rollbacks/month. Pro/Enterprise have unlimited rollbacks with instant propagation.

Troubleshooting

Common Errors

401 Unauthorized: Invalid or expired API key. Rotate via dashboard.
422 Validation Error: Schema mismatch. Run ac validate locally.
Sync Timeout: Network latency or firewall blocking WebSocket connection. Ensure port 443 is open.

Debug Mode

Enable verbose logging by setting the environment variable:

Shell

export APP_CONFIG_DEBUG=true
node app.js

Need help? Contact Support or join our Discord Community.