API Reference

This page covers the technical details of the Terraform Editor API endpoint, including request/response formats, parameters, and error codes. Whether you're sending requests via curl or integrating into a larger automation pipeline, the information here will help you structure calls correctly and interpret responses.

---

Endpoint

POST /v1/terraform/edit

• Description: Applies edits to Terraform code and returns the updated version.
• Consumes: application/json
• Produces: application/json

Note: The exact path might differ based on your deployment or reverse proxy setup. Adjust accordingly (e.g., /api/v1/terraform/edit).

---

Request Body

You send a JSON object with two primary fields:

1. code (string, required)

   • The Terraform configuration to be modified.
   • Can be empty ("") if you're starting from scratch.

2. edits (object or JSON string, required)

   • Describes the operations (add, update, set, delete) you want to perform.
   • Must include at least one of these four keys.

Request Body Schema

{
  "code": "string (Terraform code)",
  "edits": {
    "add": {
      // each key is a Terraform block type (e.g. resource, provider, data, etc.)
    },
    "update": {
      // same structure as add, but strictly updates existing resources
    },
    "set": {
      // upsert-style: create if missing, update if present
    },
    "delete": {
      // remove attributes or entire blocks
    }
  }
}

Alternatively, edits can be provided as a JSON string, which is then parsed on the server side:

{
  "code": "...",
  "edits": "{ \"add\": { ... } }"
}

Important: Only one form of edits is allowed at a time—either an object or a string containing valid JSON.

---

Response Format

On Success

{
  "success": true,
  "data": {
    "edited_code": "string (updated Terraform code)"
  },
  "message": "terraform-edit: success"
}

• edited_code: The resulting Terraform configuration after all edits have been applied.
• success: Boolean indicating the call completed successfully.
• message: A brief success message.

On Error

{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "location": "terraform-edit"
  },
  "message": "error message"
}

• error.code: A short code for the error (e.g., "INVALID_REQUEST", "MISSING_CODE", "AMBIGUOUS_MATCH", etc.).
• error.message: Describes what went wrong.
• location: Usually "terraform-edit", indicating which part of the system produced the error.
• success: False in this case.
• message: Mirrors error.message or gives additional context.

---

HTTP Status Codes

• 200 OK: Returned when the edits are successfully applied.
• 400 Bad Request:
  • Malformed JSON in the request body.
  • Missing or invalid code or edits field.
  • Ambiguous or invalid edits (e.g., multiple matches for an update, or no matches for a delete).
• 405 Method Not Allowed: Request method was not POST.
• 500 Internal Server Error: Something went wrong on the server side. Check the logs or contact support.

---

Common Error Scenarios

1. Missing code Field

   • Example: {"edits": { ... }}
   • Error: "MISSING_CODE"
   • Fix: Provide "code" in the body.

2. No Operations Provided

   • Example: {"code":"some code","edits":{}}
   • Error: "INVALID_REQUEST", must have at least one operation key (add, update, set, or delete).
   • Fix: Include at least one of the four operations.

3. Ambiguous Match

   • Scenario: Using update or delete without selectors when multiple blocks match the same label.
   • Error: "AMBIGUOUS_MATCH"
   • Fix: Use where, index, or labels to disambiguate.

4. Block Not Found

   • Scenario: update or delete references a block that doesn't exist.
   • Error: "BLOCK_NOT_FOUND" or "INVALID_REQUEST"
   • Fix: If you intended to create, use set or add. If you truly want to update/delete, ensure the block name and selectors are correct.

---

Example Request & Response

Request

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": "my-dev-rg"
                  }
                }
              }
            ]
          }
        }
      }
    }
}'

Successful Response

{
  "success": true,
  "data": {
    "edited_code": "resource \"azurerm_resource_group\" \"main\" {\n  name = \"my-dev-rg\"\n}\n"
  },
  "message": "terraform-edit: success"
}

---

Tips for Integrating the API

1. Retry Logic: Handle transient errors (e.g., HTTP 500) with a backoff strategy if you're calling the API in an automated environment.
2. Validate Terraform: After receiving the edited_code, run a quick terraform validate to ensure the resulting code is structurally correct.
3. Version Control: Consider committing or storing each returned edited_code as a new version or revision in your repository, making rollbacks and audit trails simpler.

---

Next Steps

• For an in-depth look at possible error messages and codes, see Error Handling.
• Check out the FAQ for solutions to common questions.
• Return to the Operations Reference or Selectors to master the JSON schema for edits.
• If you want more usage examples, head back to the Examples section.

Block Types

The Terraform Editor API works with well-defined Terraform block types:

• resource: Define resources to create (e.g., aws_s3_bucket)
• data: Define data sources to reference existing resources
• provider: Configure providers like AWS, GCP, Azure
• module: Reference reusable modules
• terraform: Configure Terraform itself
• output: Specify outputs from the Terraform configuration
• variable: Define input variables for the configuration
• locals: Define local values for reuse within a configuration
• tfvars: Define variable values in .tfvars files

Each block type follows the syntax established by HCL.

Operations