Quickstart

This guide will help you get up and running with the Terraform Editor API, showing how to send a minimal request and interpret the response.

Making Your First Request

The Terraform Editor API expects two main fields in the request body:

1. code: A string containing your existing Terraform configuration
2. edits: An object describing the changes you want to make

Here's a simple example that sets a new name attribute on an Azure resource group:

curl -X POST \
  'https://app-terraform-editor-api-use-dx-dev.azurewebsites.net/edit' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "resource \"azurerm_resource_group\" \"main\" {}",
    "edits": {
      "set": {
        "resource": {
          "azurerm_resource_group": {
            "main": [
              {
                "set": {
                  "attributes": {
                    "name": "this"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }'

Understanding the Request

Let's break down what's happening:

1. Starting Code: We begin with an empty resource group block
2. Edit Operation: We use set to either create or update attributes
3. Block Targeting: We specify the exact block to modify using its type and labels
4. Nested Operation: We use another set operation to define the attributes to modify

Understanding the Response

A successful response includes the updated code and metadata:

{
  "status": "success",
  "data": {
    "edited_code": "resource \"azurerm_resource_group\" \"main\" {\n  name = \"this\"\n}"
  },
  "meta": {
    "transaction_id": "terraform-edit",
    "timestamp": "2024-01-25T03:45:27.320036922Z"
  }
}

The response contains:

• status: Indicates if the operation succeeded
• data.edited_code: The modified Terraform configuration
• meta: Additional information about the request

Using the Results

Once you have the edited code, you can:

1. Save the Changes:

   echo "$EDITED_CODE" > main.tf

2. Validate the Configuration:

   terraform validate
   terraform plan

3. Apply the Changes:

   terraform apply

Common Operations

Let's look at three fundamental operations you'll commonly use:

Adding a New Resource

This example creates a new S3 bucket with various attributes and a nested block:

curl -X POST \
  'https://app-terraform-editor-api-use-dx-dev.azurewebsites.net/edit' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "",
    "edits": {
      "add": {
        "resource": {
          "aws_s3_bucket": {
            "example": [{
              "set": {
                "attributes": {
                  "bucket": "my-example-bucket",
                  "tags": {
                    "Environment": "production",
                    "Project": "example"
                  }
                },
                "blockTypes": {
                  "versioning": [{
                    "attributes": {
                      "enabled": true
                    }
                  }]
                }
              }
            }]
          }
        }
      }
    }
  }'

Updating an Existing Resource

This example modifies attributes of an existing EC2 instance:

curl -X POST \
  'https://app-terraform-editor-api-use-dx-dev.azurewebsites.net/edit' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "resource \"aws_instance\" \"web\" {\n  instance_type = \"t2.micro\"\n  ami = \"ami-123\"\n}",
    "edits": {
      "update": {
        "resource": {
          "aws_instance": {
            "web": [{
              "set": {
                "attributes": {
                  "instance_type": "t2.medium",
                  "monitoring": true
                }
              }
            }]
          }
        }
      }
    }
  }'

Deleting Resources and Attributes

This example shows how to delete an EBS block device while preserving the instance:

curl -X POST \
  'https://app-terraform-editor-api-use-dx-dev.azurewebsites.net/edit' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "resource \"aws_instance\" \"web\" {\n  instance_type = \"t2.micro\"\n  ami = \"ami-123\"\n\n  ebs_block_device {\n    device_name = \"/dev/sdh\"\n    volume_size = 20\n  }\n}",
    "edits": {
      "set": {
        "resource": {
          "aws_instance": {
            "web": [{
              "delete": {
                "blockTypes": {
                  "ebs_block_device": [{
                    "where": {
                      "device_name": "/dev/sdh"
                    }
                  }]
                }
              }
            }]
          }
        }
      }
    }
  }'

This operation removes the ebs_block_device block while preserving the instance and its other attributes. Using set at the top level ensures the instance block remains, while the nested delete operation removes the specified block type.

For more complex scenarios, including working with multiple blocks, using selectors, or handling other block types, check out our Advanced Usage guide.

Ready to Experiment?

Want to try these examples yourself? Visit our API Playground where you can:

• Test all API operations interactively
• Experiment with different Terraform configurations
• See real-time results of your edits
• Share and save your examples

Next Steps

Now that you've seen the basics, you can:

1. Explore Operations: Learn about add, update, set, and delete operations in the Operations Reference
2. Use Selectors: See how to target specific blocks using index, where, and labels in the Selectors Guide
3. Try Advanced Features: Check out Advanced Usage for complex scenarios
4. Review Best Practices: Learn about safe updates and validation in our Best Practices Guide

For detailed API specifications and error handling, visit our API Reference.