Blueprints API

The Blueprint Service provides methods for managing blueprints and accessing the blueprint catalog.

Service Definition

service BlueprintService {
  rpc CreateBlueprint(CreateBlueprintRequest) returns (Blueprint);
  rpc GetBlueprint(GetBlueprintRequest) returns (Blueprint);
  rpc ListBlueprints(ListBlueprintsRequest) returns (ListBlueprintsResponse);
  rpc UpdateBlueprint(UpdateBlueprintRequest) returns (Blueprint);
  rpc DeleteBlueprint(DeleteBlueprintRequest) returns (google.protobuf.Empty);
  rpc ValidateBlueprint(ValidateBlueprintRequest) returns (ValidateBlueprintResponse);
  rpc RenderBlueprint(RenderBlueprintRequest) returns (RenderBlueprintResponse);
  rpc SearchCatalog(SearchCatalogRequest) returns (SearchCatalogResponse);
}

CreateBlueprint

Create a new blueprint in a project.

Request

message CreateBlueprintRequest {
  string name = 1;              // Blueprint name
  string project_id = 2;        // Target project
  string content = 3;           // YAML blueprint content
  string description = 4;       // Human-readable description
  repeated string tags = 5;     // Categorization tags
}

Example

curl -X POST 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "my-workshop",
    "projectId": "proj_training",
    "content": "apiVersion: teabar.dev/v1
kind: Blueprint
metadata:
  name: my-workshop
spec:
  resources:
    - name: app
      type: helm
      spec:
        chart: nginx
        repo: https://charts.bitnami.com/bitnami",
    "description": "Simple workshop environment",
    "tags": ["workshop", "nginx"]
  }' 
  https://api.teabar.dev/teabar.v1.BlueprintService/CreateBlueprint

Response

{
  "id": "bp_abc123",
  "name": "my-workshop",
  "version": "1",
  "projectId": "proj_training",
  "description": "Simple workshop environment",
  "tags": ["workshop", "nginx"],
  "createdAt": "2024-03-10T14:30:00Z",
  "createdBy": "user_xyz"
}

GetBlueprint

Retrieve a blueprint by ID or name.

Request

message GetBlueprintRequest {
  string blueprint_id = 1;      // Blueprint ID or name
  string version = 2;           // Specific version (optional)
  bool include_content = 3;     // Include YAML content
}

Example

curl -X POST 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "blueprintId": "bp_abc123",
    "includeContent": true
  }' 
  https://api.teabar.dev/teabar.v1.BlueprintService/GetBlueprint

Response

{
  "id": "bp_abc123",
  "name": "my-workshop",
  "version": "3",
  "description": "Simple workshop environment",
  "content": "apiVersion: teabar.dev/v1
kind: Blueprint
...",
  "variables": [
    {
      "name": "replicas",
      "type": "integer",
      "default": "1",
      "description": "Number of replicas"
    }
  ],
  "resources": [
    {
      "name": "app",
      "type": "helm"
    }
  ]
}

ListBlueprints

List blueprints with filtering.

Request

message ListBlueprintsRequest {
  string project_id = 1;        // Filter by project
  repeated string tags = 2;     // Filter by tags
  int32 page_size = 3;
  string page_token = 4;
}

Example

curl -X POST 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "projectId": "proj_training",
    "tags": ["kubernetes"],
    "pageSize": 20
  }' 
  https://api.teabar.dev/teabar.v1.BlueprintService/ListBlueprints

ValidateBlueprint

Validate blueprint syntax without creating it.

Request

message ValidateBlueprintRequest {
  string content = 1;           // YAML content to validate
}

Example

curl -X POST 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "content": "apiVersion: teabar.dev/v1
kind: Blueprint
..."
  }' 
  https://api.teabar.dev/teabar.v1.BlueprintService/ValidateBlueprint

Response

{
  "valid": false,
  "errors": [
    {
      "path": "spec.resources[0].spec.chart",
      "message": "Required field missing",
      "severity": "ERROR"
    }
  ],
  "warnings": [
    {
      "path": "spec.variables[0]",
      "message": "Variable 'count' has no description",
      "severity": "WARNING"
    }
  ]
}

RenderBlueprint

Render a blueprint with variable values to preview output.

Request

message RenderBlueprintRequest {
  string blueprint_id = 1;
  map<string, string> variables = 2;
}

Example

curl -X POST 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "blueprintId": "bp_abc123",
    "variables": {
      "participant_count": "10",
      "region": "us-west"
    }
  }' 
  https://api.teabar.dev/teabar.v1.BlueprintService/RenderBlueprint

Response

{
  "rendered": "apiVersion: v1
kind: ConfigMap
metadata:
  name: workshop-config
data:
  participants: '10'
  region: us-west
---
...",
  "resources": [
    {
      "apiVersion": "v1",
      "kind": "ConfigMap",
      "name": "workshop-config"
    },
    {
      "apiVersion": "apps/v1",
      "kind": "Deployment",
      "name": "workshop-app"
    }
  ]
}

SearchCatalog

Search the public blueprint catalog.

Request

message SearchCatalogRequest {
  string query = 1;             // Search query
  repeated string tags = 2;     // Filter by tags
  string publisher = 3;         // Filter by publisher
  int32 page_size = 4;
  string page_token = 5;
}

Example

curl -X POST 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "query": "kubernetes training",
    "tags": ["workshop"],
    "pageSize": 10
  }' 
  https://api.teabar.dev/teabar.v1.BlueprintService/SearchCatalog

Response

{
  "blueprints": [
    {
      "id": "teabar/k8s-basics",
      "name": "Kubernetes Basics",
      "description": "Introduction to Kubernetes concepts",
      "publisher": "teabar",
      "tags": ["kubernetes", "workshop", "beginner"],
      "downloads": 1234,
      "rating": 4.8
    },
    {
      "id": "teabar/k8s-advanced",
      "name": "Advanced Kubernetes",
      "description": "Advanced K8s patterns and practices",
      "publisher": "teabar",
      "tags": ["kubernetes", "workshop", "advanced"],
      "downloads": 567,
      "rating": 4.9
    }
  ],
  "totalCount": 23
}

Blueprint Object

message Blueprint {
  string id = 1;
  string name = 2;
  string version = 3;
  string project_id = 4;
  string description = 5;
  repeated string tags = 6;
  string content = 7;
  repeated Variable variables = 8;
  repeated Resource resources = 9;
  Timestamp created_at = 10;
  string created_by = 11;
  Timestamp updated_at = 12;
}

Error Codes

See Also

• Environments API - Create environments from blueprints
• CLI blueprint Commands - CLI blueprint operations
• Blueprint Syntax - Blueprint YAML reference