HTTP

Defined insandbox.hcl

The http resource performs HTTP requests and captures the response. It enables labs to interact with web APIs, webhooks, and external services, making it useful for testing integrations and demonstrating API interactions.

Use Cases

As a lab author, you can use http resources to:

• External Data Integration: Fetch configuration data, API keys, or reference information from external services during lab setup
• Lab Environment Preparation: Make API calls to set up external services, register lab instances, or initialize third-party tools

HTTP resources enable lab authors to integrate external APIs and services into their lab setup and preparation workflows.

HCL Syntax

Basic Syntax

resource "http" "name" {
  method = "GET"
  url = "https://api.example.com/status"
}

Full Syntax

resource "http" "name" {
  method = "POST"
  url = "https://api.example.com/webhook"

  headers = {
    "Content-Type" = "application/json"
    "Authorization" = "Bearer token123"
    "X-Custom-Header" = "value"
  }

  payload = jsonencode({
    message = "Hello from lab"
    timestamp = "2023-12-01T10:00:00Z"
  })

  timeout = "30s"
}

Fields

Field	Type	Required	Description
method	string	✓	HTTP method (GET, POST, etc.)
url	string	✓	URL to send the request to
headers	map(string)	—	HTTP headers to send with the request
payload	string	—	Request body payload
timeout	string	—	Request timeout (e.g., '30s') ConstraintsMust be a valid duration (e.g. 30s, 5m)

Computed Attributes

These attributes are set by the system and are read-only.

Attribute	Type	Description
status	number	HTTP response status code
body	string	HTTP response body

Examples

Simple GET Request

resource "http" "api_check" {
  method = "GET"
  url = "https://httpbin.org/status/200"
}

output "api_status" {
  value = resource.http.api_check.status
}

POST with JSON Payload

resource "http" "create_user" {
  method = "POST"
  url = "https://jsonplaceholder.typicode.com/users"

  headers = {
    "Content-Type" = "application/json"
  }

  payload = jsonencode({
    name = "John Doe"
    email = "john@example.com"
    username = "johndoe"
  })
}

output "created_user" {
  value = jsondecode(resource.http.create_user.body)
}

API Authentication

resource "random_password" "api_token" {
  length = 32
  special = false
}

resource "http" "authenticate" {
  method = "POST"
  url = "https://api.example.com/auth/login"

  headers = {
    "Content-Type" = "application/json"
  }

  payload = jsonencode({
    username = "admin"
    password = "secret"
  })
}

resource "http" "protected_resource" {
  depends_on = [resource.http.authenticate]

  method = "GET"
  url = "https://api.example.com/protected/data"

  headers = {
    "Authorization" = "Bearer ${jsondecode(resource.http.authenticate.body).token}"
    "Accept" = "application/json"
  }
}

Webhook Testing

resource "http" "webhook_test" {
  method = "POST"
  url = "https://webhook.site/unique-id"

  headers = {
    "Content-Type" = "application/json"
    "X-Event-Type" = "test"
  }

  payload = jsonencode({
    event = "lab_started"
    lab_id = "introduction-to-apis"
    user_id = "student123"
    timestamp = timestamp()
  })

  timeout = "10s"
}

Configuration API Integration

resource "http" "fetch_config" {
  method = "GET"
  url = "https://api.example.com/config/v1/settings"

  headers = {
    "Accept" = "application/json"
    "Authorization" = "Bearer ${var.api_token}"
  }

  timeout = "15s"
}

resource "template" "app_config" {
  source = <<-EOF
    database:
      host: ${jsondecode(resource.http.fetch_config.body).database.host}
      port: ${jsondecode(resource.http.fetch_config.body).database.port}

    cache:
      enabled: ${jsondecode(resource.http.fetch_config.body).cache.enabled}
      ttl: ${jsondecode(resource.http.fetch_config.body).cache.ttl}
  EOF

  destination = "./config/app.yaml"
}

Service Registration

resource "http" "register_service" {
  method = "POST"
  url = "https://service-registry.example.com/api/v1/services"

  headers = {
    "Content-Type" = "application/json"
    "Authorization" = "Bearer ${var.registry_token}"
  }

  payload = jsonencode({
    name = "lab-service"
    version = "1.0.0"
    endpoints = ["http://lab-service:8080"]
    health_check = "/health"
    tags = ["lab", "demo"]
  })

  timeout = "10s"
}

External API Integration

resource "http" "github_user" {
  method = "GET"
  url = "https://api.github.com/users/octocat"

  headers = {
    "Accept" = "application/vnd.github.v3+json"
    "User-Agent" = "Instruqt-Lab"
  }
}

resource "template" "user_profile" {
  source = <<-EOF
    # GitHub User Profile

    **Name:** ${jsondecode(resource.http.github_user.body).name}
    **Username:** ${jsondecode(resource.http.github_user.body).login}
    **Followers:** ${jsondecode(resource.http.github_user.body).followers}
    **Public Repos:** ${jsondecode(resource.http.github_user.body).public_repos}
  EOF

  destination = "./github_profile.md"
}

Error Handling Pattern

resource "http" "api_test" {
  method = "GET"
  url = "https://httpbin.org/status/404"

  timeout = "10s"
}

# Check if request was successful
locals {
  api_success = resource.http.api_test.status >= 200 && resource.http.api_test.status < 300
  api_error = resource.http.api_test.status >= 400
}

output "api_result" {
  value = local.api_success ? "Success" : "Failed with status ${resource.http.api_test.status}"
}

REST API CRUD Operations

# Create
resource "http" "create_post" {
  method = "POST"
  url = "https://jsonplaceholder.typicode.com/posts"

  headers = {
    "Content-Type" = "application/json"
  }

  payload = jsonencode({
    title = "My Lab Post"
    body = "This is a test post from the lab"
    userId = 1
  })
}

# Read
resource "http" "get_post" {
  depends_on = [resource.http.create_post]

  method = "GET"
  url = "https://jsonplaceholder.typicode.com/posts/${jsondecode(resource.http.create_post.body).id}"

  headers = {
    "Accept" = "application/json"
  }
}

# Update
resource "http" "update_post" {
  depends_on = [resource.http.get_post]

  method = "PUT"
  url = "https://jsonplaceholder.typicode.com/posts/${jsondecode(resource.http.create_post.body).id}"

  headers = {
    "Content-Type" = "application/json"
  }

  payload = jsonencode({
    id = jsondecode(resource.http.create_post.body).id
    title = "Updated Lab Post"
    body = "This post has been updated"
    userId = 1
  })
}

# Delete
resource "http" "delete_post" {
  depends_on = [resource.http.update_post]

  method = "DELETE"
  url = "https://jsonplaceholder.typicode.com/posts/${jsondecode(resource.http.create_post.body).id}"
}

Response Processing

JSON Response Handling

resource "http" "json_api" {
  method = "GET"
  url = "https://jsonplaceholder.typicode.com/users/1"
}

locals {
  user_data = jsondecode(resource.http.json_api.body)
}

output "user_info" {
  value = {
    name = local.user_data.name
    email = local.user_data.email
    company = local.user_data.company.name
  }
}

Using Response Data

resource "http" "config_api" {
  method = "GET"
  url = "https://api.example.com/config"

  headers = {
    "Accept" = "application/json"
  }
}

resource "template" "app_config" {
  source = <<-EOF
    database:
      host: ${jsondecode(resource.http.config_api.body).database.host}
      port: ${jsondecode(resource.http.config_api.body).database.port}

    cache:
      enabled: ${jsondecode(resource.http.config_api.body).cache.enabled}
  EOF

  destination = "./config/app.yaml"
}

Best Practices

1. Timeouts: Set appropriate timeouts for external API calls
2. Error Handling: Check status codes and handle errors appropriately
3. Authentication: Securely handle API keys and tokens
4. Rate Limiting: Be mindful of API rate limits in lab scenarios
5. Headers: Include proper headers (User-Agent, Accept, Content-Type)
6. Dependencies: Use depends_on for proper resource ordering
7. Sensitive Data: Mark sensitive outputs appropriately