attune-system/attune
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

re-uploading work

Browse Source
This commit is contained in:
David Culbreth
2026-02-04 17:46:30 -06:00
commit 3b14c65998
1388 changed files with 381262 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

752
docs/api/api-packs.md Normal file
View File

@@ -0,0 +1,752 @@
# Pack Management API
This document provides comprehensive documentation for the Pack Management API endpoints in Attune.
## Overview
Packs are containers that bundle related automation components (actions, triggers, rules, and sensors) together. They provide:
- **Organization**: Group related automation components by domain or service
- **Versioning**: Track and manage versions of automation components
- **Configuration**: Define pack-level configuration schemas and defaults
- **Dependencies**: Declare runtime and pack dependencies
- **Metadata**: Store tags, descriptions, and other metadata
## Pack Data Model
### Pack Structure
```json
{
"id": 1,
"ref": "aws.ec2",
"label": "AWS EC2 Pack",
"description": "Actions and triggers for AWS EC2 management",
"version": "1.0.0",
"conf_schema": {
"type": "object",
"properties": {
"region": {"type": "string"},
"access_key_id": {"type": "string"},
"secret_access_key": {"type": "string"}
},
"required": ["region"]
},
"config": {
"region": "us-east-1"
},
"meta": {
"author": "Attune Team",
"license": "MIT"
},
"tags": ["aws", "ec2", "cloud"],
"runtime_deps": [1, 2],
"is_standard": true,
"created": "2024-01-15T10:30:00Z",
"updated": "2024-01-15T10:30:00Z"
}
```
### Field Descriptions
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | integer | auto | Unique pack identifier |
| `ref` | string | yes | Unique reference (e.g., "aws.ec2", "core.http") |
| `label` | string | yes | Human-readable pack name |
| `description` | string | yes | Pack description and purpose |
| `version` | string | no | Semantic version (e.g., "1.0.0") |
| `conf_schema` | object | no | JSON Schema for pack configuration |
| `config` | object | no | Default pack configuration values |
| `meta` | object | no | Additional metadata (author, license, etc.) |
| `tags` | array | no | Tags for categorization and search |
| `runtime_deps` | array | no | Runtime IDs this pack depends on |
| `is_standard` | boolean | no | Whether this is a standard/built-in pack |
| `created` | timestamp | auto | Creation timestamp |
| `updated` | timestamp | auto | Last update timestamp |
## API Endpoints
### 1. List Packs
Retrieve a paginated list of all packs.
**Endpoint:** `GET /api/v1/packs`
**Query Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | integer | 1 | Page number (1-based) |
| `per_page` | integer | 50 | Items per page (max: 100) |
**Example Request:**
```bash
curl -X GET "http://localhost:3000/api/v1/packs?page=1&per_page=20" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Example Response:**
```json
{
"data": [
{
"id": 1,
"ref": "core.http",
"label": "HTTP Core Pack",
"description": "HTTP actions and triggers",
"version": "1.0.0",
"tags": ["http", "core"],
"is_standard": true,
"created": "2024-01-15T10:30:00Z",
"updated": "2024-01-15T10:30:00Z"
},
{
"id": 2,
"ref": "aws.ec2",
"label": "AWS EC2 Pack",
"description": "AWS EC2 management",
"version": "1.0.0",
"tags": ["aws", "ec2", "cloud"],
"is_standard": false,
"created": "2024-01-16T14:20:00Z",
"updated": "2024-01-16T14:20:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 2,
"total_pages": 1
}
}
```
### 2. Get Pack by Reference
Retrieve a specific pack by its reference identifier.
**Endpoint:** `GET /api/v1/packs/:ref`
**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `ref` | string | Pack reference (e.g., "aws.ec2") |
**Example Request:**
```bash
curl -X GET "http://localhost:3000/api/v1/packs/aws.ec2" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Example Response:**
```json
{
"data": {
"id": 2,
"ref": "aws.ec2",
"label": "AWS EC2 Pack",
"description": "Actions and triggers for AWS EC2 management",
"version": "1.0.0",
"conf_schema": {
"type": "object",
"properties": {
"region": {"type": "string"},
"access_key_id": {"type": "string"}
}
},
"config": {
"region": "us-east-1"
},
"meta": {
"author": "Attune Team"
},
"tags": ["aws", "ec2", "cloud"],
"runtime_deps": [1],
"is_standard": false,
"created": "2024-01-16T14:20:00Z",
"updated": "2024-01-16T14:20:00Z"
}
}
```
### 3. Create Pack
Create a new pack.
**Endpoint:** `POST /api/v1/packs`
**Request Body:**
```json
{
"ref": "slack.notifications",
"label": "Slack Notifications Pack",
"description": "Actions for sending Slack notifications",
"version": "1.0.0",
"conf_schema": {
"type": "object",
"properties": {
"webhook_url": {"type": "string"},
"default_channel": {"type": "string"}
},
"required": ["webhook_url"]
},
"config": {
"default_channel": "#general"
},
"meta": {
"author": "Your Team",
"license": "MIT"
},
"tags": ["slack", "notifications", "messaging"],
"runtime_deps": [1],
"is_standard": false
}
```
**Example Request:**
```bash
curl -X POST "http://localhost:3000/api/v1/packs" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ref": "slack.notifications",
"label": "Slack Notifications Pack",
"description": "Actions for sending Slack notifications",
"version": "1.0.0",
"tags": ["slack", "notifications"],
"is_standard": false
}'
```
**Example Response:**
```json
{
"data": {
"id": 3,
"ref": "slack.notifications",
"label": "Slack Notifications Pack",
"description": "Actions for sending Slack notifications",
"version": "1.0.0",
"conf_schema": null,
"config": null,
"meta": null,
"tags": ["slack", "notifications"],
"runtime_deps": [],
"is_standard": false,
"created": "2024-01-17T09:15:00Z",
"updated": "2024-01-17T09:15:00Z"
},
"message": "Pack created successfully"
}
```
**Status Codes:**
- `201 Created`: Pack created successfully
- `400 Bad Request`: Invalid request data or validation error
- `409 Conflict`: Pack with the same ref already exists
### 4. Update Pack
Update an existing pack.
**Endpoint:** `PUT /api/v1/packs/:ref`
**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `ref` | string | Pack reference to update |
**Request Body:** (all fields optional)
```json
{
"label": "Updated Pack Label",
"description": "Updated description",
"version": "1.1.0",
"conf_schema": {...},
"config": {...},
"meta": {...},
"tags": ["updated", "tags"],
"runtime_deps": [1, 2],
"is_standard": false
}
```
**Example Request:**
```bash
curl -X PUT "http://localhost:3000/api/v1/packs/slack.notifications" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"version": "1.1.0",
"description": "Enhanced Slack notifications with rich formatting"
}'
```
**Example Response:**
```json
{
"data": {
"id": 3,
"ref": "slack.notifications",
"label": "Slack Notifications Pack",
"description": "Enhanced Slack notifications with rich formatting",
"version": "1.1.0",
"conf_schema": null,
"config": null,
"meta": null,
"tags": ["slack", "notifications"],
"runtime_deps": [],
"is_standard": false,
"created": "2024-01-17T09:15:00Z",
"updated": "2024-01-17T09:30:00Z"
},
"message": "Pack updated successfully"
}
```
**Status Codes:**
- `200 OK`: Pack updated successfully
- `400 Bad Request`: Invalid request data or validation error
- `404 Not Found`: Pack not found
### 5. Delete Pack
Delete a pack and all its associated components.
**Endpoint:** `DELETE /api/v1/packs/:ref`
**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `ref` | string | Pack reference to delete |
**Example Request:**
```bash
curl -X DELETE "http://localhost:3000/api/v1/packs/slack.notifications" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Example Response:**
```json
{
"success": true,
"message": "Pack 'slack.notifications' deleted successfully"
}
```
**Status Codes:**
- `200 OK`: Pack deleted successfully
- `404 Not Found`: Pack not found
**Warning:** Deleting a pack will cascade delete all actions, triggers, rules, and sensors that belong to it. This operation cannot be undone.
### 6. List Pack Actions
Retrieve all actions that belong to a specific pack.
**Endpoint:** `GET /api/v1/packs/:ref/actions`
**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `ref` | string | Pack reference |
**Example Request:**
```bash
curl -X GET "http://localhost:3000/api/v1/packs/aws.ec2/actions" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Example Response:**
```json
{
"data": [
{
"id": 1,
"ref": "aws.ec2.start_instance",
"pack_ref": "aws.ec2",
"label": "Start EC2 Instance",
"description": "Start an EC2 instance",
"runtime": 1,
"created": "2024-01-16T14:30:00Z",
"updated": "2024-01-16T14:30:00Z"
},
{
"id": 2,
"ref": "aws.ec2.stop_instance",
"pack_ref": "aws.ec2",
"label": "Stop EC2 Instance",
"description": "Stop an EC2 instance",
"runtime": 1,
"created": "2024-01-16T14:35:00Z",
"updated": "2024-01-16T14:35:00Z"
}
]
}
```
**Status Codes:**
- `200 OK`: Actions retrieved successfully (empty array if none)
- `404 Not Found`: Pack not found
### 7. List Pack Triggers
Retrieve all triggers that belong to a specific pack.
**Endpoint:** `GET /api/v1/packs/:ref/triggers`
**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `ref` | string | Pack reference |
**Example Request:**
```bash
curl -X GET "http://localhost:3000/api/v1/packs/aws.ec2/triggers" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Example Response:**
```json
{
"data": [
{
"id": 1,
"ref": "aws.ec2.instance_state_change",
"pack_ref": "aws.ec2",
"label": "EC2 Instance State Change",
"description": "Triggered when EC2 instance state changes",
"enabled": true,
"created": "2024-01-16T14:40:00Z",
"updated": "2024-01-16T14:40:00Z"
}
]
}
```
**Status Codes:**
- `200 OK`: Triggers retrieved successfully (empty array if none)
- `404 Not Found`: Pack not found
### 8. List Pack Rules
Retrieve all rules that belong to a specific pack.
**Endpoint:** `GET /api/v1/packs/:ref/rules`
**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `ref` | string | Pack reference |
**Example Request:**
```bash
curl -X GET "http://localhost:3000/api/v1/packs/aws.ec2/rules" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Example Response:**
```json
{
"data": [
{
"id": 1,
"ref": "aws.ec2.auto_stop_idle",
"pack_ref": "aws.ec2",
"label": "Auto-stop Idle Instances",
"description": "Automatically stop idle EC2 instances",
"action_ref": "aws.ec2.stop_instance",
"trigger_ref": "aws.ec2.instance_state_change",
"enabled": true,
"created": "2024-01-16T15:00:00Z",
"updated": "2024-01-16T15:00:00Z"
}
]
}
```
**Status Codes:**
- `200 OK`: Rules retrieved successfully (empty array if none)
- `404 Not Found`: Pack not found
## Pack Lifecycle
### 1. Pack Creation Workflow
```
1. Define pack metadata (ref, label, description)
2. Create configuration schema (optional)
3. Set default configuration values (optional)
4. Add metadata and tags
5. Specify runtime dependencies
6. POST to /api/v1/packs
7. Create pack actions, triggers, and rules
```
### 2. Pack Update Workflow
```
1. Retrieve current pack details (GET /api/v1/packs/:ref)
2. Modify desired fields
3. Update pack (PUT /api/v1/packs/:ref)
4. Update version number if making breaking changes
5. Update dependent components if needed
```
### 3. Pack Deletion Workflow
```
1. List all pack components:
- GET /api/v1/packs/:ref/actions
- GET /api/v1/packs/:ref/triggers
- GET /api/v1/packs/:ref/rules
2. Verify no critical dependencies
3. Backup pack configuration if needed
4. DELETE /api/v1/packs/:ref
5. All components cascade deleted automatically
```
## Configuration Schema
Packs can define a JSON Schema for their configuration. This schema validates pack configuration values and provides documentation for users.
### Example Configuration Schema
```json
{
"type": "object",
"properties": {
"api_key": {
"type": "string",
"description": "API key for authentication"
},
"region": {
"type": "string",
"enum": ["us-east-1", "us-west-2", "eu-west-1"],
"default": "us-east-1",
"description": "AWS region"
},
"timeout": {
"type": "integer",
"minimum": 1000,
"maximum": 30000,
"default": 5000,
"description": "Request timeout in milliseconds"
},
"retry_count": {
"type": "integer",
"minimum": 0,
"maximum": 5,
"default": 3,
"description": "Number of retry attempts"
}
},
"required": ["api_key", "region"]
}
```
### Using Configuration in Actions
Actions within a pack can access pack configuration:
```python
# In an action's Python script
pack_config = context.pack.config
api_key = pack_config.get("api_key")
region = pack_config.get("region", "us-east-1")
```
## Best Practices
### Pack Design
1. **Single Responsibility**: Each pack should focus on a specific domain or service
2. **Versioning**: Use semantic versioning (MAJOR.MINOR.PATCH)
3. **Documentation**: Provide clear descriptions for pack and configuration
4. **Dependencies**: Minimize runtime dependencies when possible
5. **Configuration**: Use sensible defaults in configuration schemas
### Naming Conventions
- **Pack Ref**: Use dot notation (e.g., "aws.ec2", "slack.notifications")
- **Labels**: Use title case (e.g., "AWS EC2 Pack")
- **Tags**: Use lowercase, kebab-case if needed (e.g., "aws", "cloud-provider")
### Security
1. **Secrets**: Never store secrets in pack configuration
2. **Schema**: Define strict configuration schemas
3. **Validation**: Validate all configuration values
4. **Access Control**: Limit pack modification to authorized users
### Organization
1. **Standard Packs**: Mark built-in/core packs as `is_standard: true`
2. **Tagging**: Use consistent tags for discoverability
3. **Metadata**: Include author, license, and documentation URLs
4. **Dependencies**: Document runtime requirements clearly
## Error Handling
### Common Error Responses
**404 Not Found:**
```json
{
"error": "Pack 'nonexistent.pack' not found"
}
```
**409 Conflict:**
```json
{
"error": "Pack with ref 'aws.ec2' already exists"
}
```
**400 Bad Request:**
```json
{
"error": "Validation failed",
"details": {
"ref": ["Must be between 1 and 255 characters"],
"label": ["Field is required"]
}
}
```
## Integration Examples
### Creating a Complete Pack
```bash
#!/bin/bash
# 1. Create the pack
PACK_ID=$(curl -X POST "http://localhost:3000/api/v1/packs" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ref": "monitoring.healthcheck",
"label": "Health Check Monitoring",
"description": "Monitor endpoint health",
"version": "1.0.0",
"tags": ["monitoring", "health"],
"is_standard": false
}' | jq -r '.data.id')
# 2. Create a trigger
curl -X POST "http://localhost:3000/api/v1/triggers" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ref": "monitoring.healthcheck.endpoint_down",
"pack_ref": "monitoring.healthcheck",
"label": "Endpoint Down",
"description": "Triggered when endpoint is unreachable"
}'
# 3. Create an action
curl -X POST "http://localhost:3000/api/v1/actions" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ref": "monitoring.healthcheck.send_alert",
"pack_ref": "monitoring.healthcheck",
"label": "Send Alert",
"description": "Send notification about endpoint status",
"entrypoint": "actions/send_alert.py",
"runtime": 1
}'
# 4. Create a rule
curl -X POST "http://localhost:3000/api/v1/rules" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ref": "monitoring.healthcheck.alert_on_down",
"pack_ref": "monitoring.healthcheck",
"label": "Alert on Down",
"description": "Send alert when endpoint goes down",
"action_ref": "monitoring.healthcheck.send_alert",
"trigger_ref": "monitoring.healthcheck.endpoint_down",
"enabled": true
}'
echo "Pack created successfully!"
```
### Listing Pack Components
```bash
#!/bin/bash
PACK_REF="aws.ec2"
echo "=== Pack Details ==="
curl -s "http://localhost:3000/api/v1/packs/$PACK_REF" \
-H "Authorization: Bearer $TOKEN" | jq '.data'
echo -e "\n=== Actions ==="
curl -s "http://localhost:3000/api/v1/packs/$PACK_REF/actions" \
-H "Authorization: Bearer $TOKEN" | jq '.data[] | {ref, label}'
echo -e "\n=== Triggers ==="
curl -s "http://localhost:3000/api/v1/packs/$PACK_REF/triggers" \
-H "Authorization: Bearer $TOKEN" | jq '.data[] | {ref, label}'
echo -e "\n=== Rules ==="
curl -s "http://localhost:3000/api/v1/packs/$PACK_REF/rules" \
-H "Authorization: Bearer $TOKEN" | jq '.data[] | {ref, label, enabled}'
```
## Related Documentation
- [Action Management API](api-actions.md)
- [Trigger & Sensor Management API](api-triggers-sensors.md)
- [Rule Management API](api-rules.md)
- [Authentication Guide](authentication.md)
## Summary
The Pack Management API provides:
- ✅ Full CRUD operations for packs
- ✅ Pack component listing (actions, triggers, rules)
- ✅ Configuration schema support
- ✅ Version management
- ✅ Dependency tracking
- ✅ Comprehensive validation and error handling
Packs are the organizational foundation of Attune, enabling modular and reusable automation components.