Publish via API

Publish blueprints programmatically using the Bluebricks API for custom automation and integration scenarios.

Prerequisites

Bluebricks API key with publish permissions
Blueprint source code and configuration
HTTP client (curl, Python requests, etc.)
Understanding of Bluebricks API endpoints

API Endpoints

Base URL

https://api.bluebricks.co/api/v1

Authentication

All API requests require authentication:

Authorization: Bearer YOUR_API_KEY

Publishing Workflow

Step 1: Prepare Blueprint Package

First, create a package containing your blueprint:

# Create package payload
curl -X POST https://api.bluebricks.co/api/v1/packages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_blueprint",
    "version": "1.0.0",
    "description": "My custom blueprint",
    "type": "blueprint",
    "source": {
      "type": "git",
      "url": "https://github.com/user/repo",
      "ref": "main"
    }
  }'

Step 2: Upload Blueprint Files

Upload blueprint configuration and source files:

# Upload bricks.json configuration
curl -X POST https://api.bluebricks.co/api/v1/packages/{package_id}/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@bricks.json" \
  -F "path=/" \
  -F "type=config"

# Upload source files
curl -X POST https://api.bluebricks.co/api/v1/packages/{package_id}/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@terraform/main.tf" \
  -F "path=/terraform/" \
  -F "type=source"

Step 3: Publish Blueprint

Publish the blueprint to make it available:

curl -X POST https://api.bluebricks.co/api/v1/packages/{package_id}/publish \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0.0",
    "description": "Initial release",
    "changelog": "First version of the blueprint"
  }'

Complete Example

Python Implementation

import requests
import json
import os
from pathlib import Path

class BluebricksPublisher:
    def __init__(self, api_key, base_url="https://api.bluebricks.co/api/v1"):
        self.api_key = api_key
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
    
    def create_package(self, name, version, description, source_url):
        """Create a new package"""
        payload = {
            "name": name,
            "version": version,
            "description": description,
            "type": "blueprint",
            "source": {
                "type": "git",
                "url": source_url,
                "ref": "main"
            }
        }
        
        response = requests.post(
            f"{self.base_url}/packages",
            headers=self.headers,
            json=payload
        )
        response.raise_for_status()
        return response.json()
    
    def upload_file(self, package_id, file_path, target_path="/"):
        """Upload a file to the package"""
        files = {
            "file": open(file_path, "rb")
        }
        data = {
            "path": target_path,
            "type": "source"
        }
        
        headers = {"Authorization": f"Bearer {self.api_key}"}
        
        response = requests.post(
            f"{self.base_url}/packages/{package_id}/files",
            headers=headers,
            files=files,
            data=data
        )
        response.raise_for_status()
        return response.json()
    
    def publish_blueprint(self, package_id, version, description, changelog):
        """Publish the blueprint"""
        payload = {
            "version": version,
            "description": description,
            "changelog": changelog
        }
        
        response = requests.post(
            f"{self.base_url}/packages/{package_id}/publish",
            headers=self.headers,
            json=payload
        )
        response.raise_for_status()
        return response.json()

# Usage example
def publish_blueprint_from_directory(blueprint_dir, api_key):
    publisher = BluebricksPublisher(api_key)
    
    # Read bricks.json
    bricks_config = json.load(open(Path(blueprint_dir) / "bricks.json"))
    
    # Create package
    package = publisher.create_package(
        name=bricks_config["name"],
        version=bricks_config["version"],
        description=bricks_config["description"],
        source_url="https://github.com/user/repo"
    )
    
    package_id = package["id"]
    
    # Upload configuration file
    publisher.upload_file(
        package_id,
        Path(blueprint_dir) / "bricks.json",
        "/"
    )
    
    # Upload source files
    for tf_file in Path(blueprint_dir).glob("*.tf"):
        publisher.upload_file(
            package_id,
            tf_file,
            f"/terraform/{tf_file.name}"
        )
    
    # Publish blueprint
    result = publisher.publish_blueprint(
        package_id,
        bricks_config["version"],
        bricks_config["description"],
        "Published via API"
    )
    
    print(f"Blueprint published successfully: {result}")
    return result

# Example usage
if __name__ == "__main__":
    api_key = os.getenv("BRICKS_API_KEY")
    blueprint_dir = "./my_blueprint"
    
    publish_blueprint_from_directory(blueprint_dir, api_key)

Bash Script Implementation

#!/bin/bash
set -e

# Configuration
API_KEY="${BRICKS_API_KEY}"
BASE_URL="https://api.bluebricks.co/api/v1"
BLUEPRINT_DIR="./my_blueprint"

# Read blueprint configuration
BLUEPRINT_NAME=$(jq -r '.name' "$BLUEPRINT_DIR/bricks.json")
BLUEPRINT_VERSION=$(jq -r '.version' "$BLUEPRINT_DIR/bricks.json")
BLUEPRINT_DESCRIPTION=$(jq -r '.description' "$BLUEPRINT_DIR/bricks.json")

echo "Publishing blueprint: $BLUEPRINT_NAME v$BLUEPRINT_VERSION"

# Create package
PACKAGE_RESPONSE=$(curl -s -X POST "$BASE_URL/packages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"$BLUEPRINT_NAME\",
    \"version\": \"$BLUEPRINT_VERSION\",
    \"description\": \"$BLUEPRINT_DESCRIPTION\",
    \"type\": \"blueprint\",
    \"source\": {
      \"type\": \"git\",
      \"url\": \"https://github.com/user/repo\",
      \"ref\": \"main\"
    }
  }")

PACKAGE_ID=$(echo "$PACKAGE_RESPONSE" | jq -r '.id')
echo "Created package: $PACKAGE_ID"

# Upload configuration file
curl -s -X POST "$BASE_URL/packages/$PACKAGE_ID/files" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@$BLUEPRINT_DIR/bricks.json" \
  -F "path=/" \
  -F "type=config"

echo "Uploaded configuration file"

# Upload source files
for file in "$BLUEPRINT_DIR"/*.tf; do
  if [ -f "$file" ]; then
    filename=$(basename "$file")
    curl -s -X POST "$BASE_URL/packages/$PACKAGE_ID/files" \
      -H "Authorization: Bearer $API_KEY" \
      -F "file=@$file" \
      -F "path=/terraform/$filename" \
      -F "type=source"
    echo "Uploaded: $filename"
  fi
done

# Publish blueprint
PUBLISH_RESPONSE=$(curl -s -X POST "$BASE_URL/packages/$PACKAGE_ID/publish" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"version\": \"$BLUEPRINT_VERSION\",
    \"description\": \"$BLUEPRINT_DESCRIPTION\",
    \"changelog\": \"Published via API\"
  }")

echo "Blueprint published successfully!"
echo "$PUBLISH_RESPONSE" | jq '.'

Error Handling

Common API Errors

def handle_api_error(response):
    """Handle API errors gracefully"""
    if response.status_code == 401:
        raise Exception("Authentication failed. Check your API key.")
    elif response.status_code == 403:
        raise Exception("Permission denied. Check your API key permissions.")
    elif response.status_code == 404:
        raise Exception("Resource not found.")
    elif response.status_code == 409:
        raise Exception("Conflict. Resource may already exist.")
    elif response.status_code >= 400:
        error_detail = response.json().get('detail', 'Unknown error')
        raise Exception(f"API error {response.status_code}: {error_detail}")

Retry Logic

import time
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def create_session_with_retries():
    """Create requests session with retry logic"""
    session = requests.Session()
    
    retry_strategy = Retry(
        total=3,
        backoff_factor=1,
        status_forcelist=[429, 500, 502, 503, 504],
    )
    
    adapter = HTTPAdapter(max_retries=retry_strategy)
    session.mount("http://", adapter)
    session.mount("https://", adapter)
    
    return session

Advanced Features

Batch Publishing

def publish_multiple_blueprints(blueprint_configs, api_key):
    """Publish multiple blueprints in batch"""
    publisher = BluebricksPublisher(api_key)
    results = []
    
    for config in blueprint_configs:
        try:
            result = publisher.publish_blueprint_from_config(config)
            results.append({"config": config, "result": result, "status": "success"})
        except Exception as e:
            results.append({"config": config, "error": str(e), "status": "failed"})
    
    return results

Version Management

def get_package_versions(package_id, api_key):
    """Get all versions of a package"""
    response = requests.get(
        f"https://api.bluebricks.co/api/v1/packages/{package_id}/versions",
        headers={"Authorization": f"Bearer {api_key}"}
    )
    response.raise_for_status()
    return response.json()

def compare_versions(version1, version2):
    """Compare semantic versions"""
    from packaging import version
    return version.parse(version1) > version.parse(version2)

Best Practices

Security

Store API keys securely (environment variables, secret management)
Use HTTPS for all API requests
Implement proper error handling
Log API calls for audit purposes

Performance

Use connection pooling for multiple requests
Implement retry logic with exponential backoff
Batch operations when possible
Cache responses when appropriate

Monitoring

Track API usage and rate limits
Monitor publishing success rates
Set up alerts for failed publications
Log all API interactions

Good night

Publish via API

Prerequisites

API Endpoints

Base URL

Authentication

Publishing Workflow

Step 1: Prepare Blueprint Package

Step 2: Upload Blueprint Files

Step 3: Publish Blueprint

Complete Example

Python Implementation

Bash Script Implementation

Error Handling

Common API Errors

Retry Logic

Advanced Features

Batch Publishing

Version Management

Best Practices

Security

Performance

Monitoring

See also

Good night

hashtagPrerequisites

hashtagAPI Endpoints

hashtagBase URL

hashtagAuthentication

hashtagPublishing Workflow

hashtagStep 1: Prepare Blueprint Package

hashtagStep 2: Upload Blueprint Files

hashtagStep 3: Publish Blueprint

hashtagComplete Example

hashtagPython Implementation

hashtagBash Script Implementation

hashtagError Handling

hashtagCommon API Errors

hashtagRetry Logic

hashtagAdvanced Features

hashtagBatch Publishing

hashtagVersion Management

hashtagBest Practices

hashtagSecurity

hashtagPerformance

hashtagMonitoring

hashtagSee also

Prerequisites

API Endpoints

Base URL

Authentication

Publishing Workflow

Step 1: Prepare Blueprint Package

Step 2: Upload Blueprint Files

Step 3: Publish Blueprint

Complete Example

Python Implementation

Bash Script Implementation

Error Handling

Common API Errors

Retry Logic

Advanced Features

Batch Publishing

Version Management

Best Practices

Security

Performance

Monitoring

See also