HTTP

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	Required	Type	Description
method	✓	string	HTTP method (GET, POST, PUT, DELETE, etc.)
url	✓	string	Target URL for the HTTP request
headers		map(string)	HTTP headers to send with the request. Defaults to empty map.
payload		string	Request body/payload
timeout		string	Request timeout duration. Defaults to ”30s”.

Computed Attributes

These attributes are set by the system after the HTTP request completes:

Field	Type	Description
status	int	HTTP status code returned by the server
body	string	Response body content

Validation Rules

• URL must be a valid HTTP/HTTPS URL
• Method must be a valid HTTP method
• Timeout must be a valid Go duration string
• Headers must be valid HTTP header names and values

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