Feature/issue 300 - Http Resource

README.md

@@ -1,8 +1,10 @@
 # Terraform Provider: HTTP
 
 The HTTP provider interacts with generic HTTP servers. 
-It provides a data source that issues an HTTP request exposing the response headers and body
-for use within a Terraform deployment.
+It provides:
+
+- a data source (`http`) that issues an HTTP request exposing the response headers and body.
+- a resource (`http`) that performs an HTTP request during apply and stores response data in state.
 
 ## Documentation, questions and discussions
 

docs/cdktf/python/resources/http.md

@@ -0,0 +1,233 @@
+---
+page_title: "http Resource - terraform-provider-http"
+subcategory: ""
+description: |-
+  The http resource makes an HTTP request to the given URL and exports
+  information about the response.
+  The given URL may be either an http or https URL. This resource
+  will issue a warning if the result is not UTF-8 encoded.
+  ~> Important Although https URLs can be used, there is currently no
+  mechanism to authenticate the remote server except for general verification of
+  the server certificate's chain of trust. Data retrieved from servers not under
+  your control should be treated as untrustworthy.
+  By default, there are no retries. Configuring the retry block will result in
+  retries if an error is returned by the client (e.g., connection errors) or if
+  a 5xx-range (except 501) status code is received. For further details see
+  go-retryablehttp https://pkg.go.dev/github.com/hashicorp/go-retryablehttp.
+---
+
+
+<!-- Please do not edit this file, it is generated. -->
+# http (Resource)
+
+The `http` resource makes an HTTP request to the given URL and exports
+information about the response.
+
+The given URL may be either an `http` or `https` URL. This resource
+will issue a warning if the result is not UTF-8 encoded.
+
+~> **Important** Although `https` URLs can be used, there is currently no
+mechanism to authenticate the remote server except for general verification of
+the server certificate's chain of trust. Data retrieved from servers not under
+your control should be treated as untrustworthy.
+
+By default, there are no retries. Configuring the retry block will result in
+retries if an error is returned by the client (e.g., connection errors) or if 
+a 5xx-range (except 501) status code is received. For further details see 
+[go-retryablehttp](https://pkg.go.dev/github.com/hashicorp/go-retryablehttp).
+
+## Example Usage
+
+```python
+# DO NOT EDIT. Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug
+from constructs import Construct
+from cdktf import TerraformStack
+#
+# Provider bindings are generated by running `cdktf get`.
+# See https://cdk.tf/provider-generation for more details.
+#
+from imports.http. import ResourceHttp
+class MyConvertedCode(TerraformStack):
+    def __init__(self, scope, name):
+        super().__init__(scope, name)
+        ResourceHttp(self, "example",
+            request_headers=[{
+                "Accept": "application/json"
+            }
+            ],
+            url="https://checkpoint-api.hashicorp.com/v1/check/terraform"
+        )
+        ResourceHttp(self, "example_head",
+            method="HEAD",
+            url="https://checkpoint-api.hashicorp.com/v1/check/terraform"
+        )
+        ResourceHttp(self, "example_post",
+            method="POST",
+            request_body="request body",
+            url="https://checkpoint-api.hashicorp.com/v1/check/terraform"
+        )
+```
+
+## Controlling when the request is sent
+
+Use the resource argument `when` to control whether the HTTP request is executed during apply operations or only during destroy:
+
+- `apply` (default): request is executed during create and update.
+- `destroy`: request is executed only during resource destruction.
+
+```python
+# DO NOT EDIT. Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug
+from constructs import Construct
+from cdktf import TerraformStack
+from imports.http. import ResourceHttp
+class MyConvertedCode(TerraformStack):
+    def __init__(self, scope, name):
+        super().__init__(scope, name)
+        ResourceHttp(self, "cleanup",
+            method="DELETE",
+            url="https://api.example.com/cleanup",
+            when="destroy"
+        )
+```
+
+## Usage with Postcondition
+
+Note: Pre/postconditions validate values during apply. They are only meaningful when the resource executes the HTTP request during apply, i.e., when `when = "apply"` (default). If `when = "destroy"`, these conditions will not evaluate against a fresh request result.
+
+```python
+# DO NOT EDIT. Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug
+from constructs import Construct
+from cdktf import TerraformSelf, Fn, TerraformStack
+#
+# Provider bindings are generated by running `cdktf get`.
+# See https://cdk.tf/provider-generation for more details.
+#
+from imports.http. import ResourceHttp
+class MyConvertedCode(TerraformStack):
+    def __init__(self, scope, name):
+        super().__init__(scope, name)
+        ResourceHttp(self, "example",
+            lifecycle={
+                "postcondition": [{
+                    "condition": Fn.contains([201, 204],
+                    TerraformSelf.get_any("status_code")),
+                    "error_message": "Status code invalid"
+                }
+                ]
+            },
+            request_headers=[{
+                "Accept": "application/json"
+            }
+            ],
+            url="https://checkpoint-api.hashicorp.com/v1/check/terraform",
+            when="apply"
+        )
+```
+
+## Usage with Precondition
+
+Note: Pre/postconditions validate values during apply. They are only meaningful when the resource executes the HTTP request during apply, i.e., when `when = "apply"` (default). If `when = "destroy"`, these conditions will not evaluate against a fresh request result.
+
+```python
+# DO NOT EDIT. Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug
+from constructs import Construct
+from cdktf import Fn, TerraformStack
+#
+# Provider bindings are generated by running `cdktf get`.
+# See https://cdk.tf/provider-generation for more details.
+#
+from imports.http. import ResourceHttp
+class MyConvertedCode(TerraformStack):
+    def __init__(self, scope, name):
+        super().__init__(scope, name)
+        http_example = ResourceHttp(self, "example",
+            request_headers=[{
+                "Accept": "application/json"
+            }
+            ],
+            url="https://checkpoint-api.hashicorp.com/v1/check/terraform",
+            when="apply"
+        )
+        http_example.add_override("lifecycle.precondition", [{
+            "condition": Fn.contains([200, 201, 204], http_example.status_code),
+            "error_message": "Unexpected status code"
+        }
+        ])
+```
+
+## Usage with Provisioner
+
+[Failure Behaviour](https://www.terraform.io/language/resources/provisioners/syntax#failure-behavior)
+can be leveraged within a provisioner in order to raise an error and stop applying.
+
+```python
+# DO NOT EDIT. Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug
+from constructs import Construct
+from cdktf import Fn, TerraformStack
+#
+# Provider bindings are generated by running `cdktf get`.
+# See https://cdk.tf/provider-generation for more details.
+#
+from imports.null.resource import Resource
+from imports.http. import ResourceHttp
+class MyConvertedCode(TerraformStack):
+    def __init__(self, scope, name):
+        super().__init__(scope, name)
+        http_example = ResourceHttp(self, "example",
+            request_headers=[{
+                "Accept": "application/json"
+            }
+            ],
+            url="https://checkpoint-api.hashicorp.com/v1/check/terraform"
+        )
+        null_provider_resource_example = Resource(self, "example_1",
+            provisioners=[{
+                "type": "local-exec",
+                "command": Fn.contains([201, 204], http_example.status_code)
+            }
+            ]
+        )
+        # This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.
+        null_provider_resource_example.override_logical_id("example")
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `url` (String) The URL for the request. Supported schemes are `http` and `https`.
+
+### Optional
+
+- `ca_cert_pem` (String) Certificate Authority (CA) in [PEM (RFC 1421)](https://datatracker.ietf.org/doc/html/rfc1421) format.
+- `client_cert_pem` (String) Client certificate in [PEM (RFC 1421)](https://datatracker.ietf.org/doc/html/rfc1421) format.
+- `client_key_pem` (String) Client key in [PEM (RFC 1421)](https://datatracker.ietf.org/doc/html/rfc1421) format.
+- `insecure` (Boolean) Disables verification of the server's certificate chain and hostname. Defaults to `false`
+- `method` (String) The HTTP Method for the request. Allowed methods are a subset of methods defined in [RFC7231](https://datatracker.ietf.org/doc/html/rfc7231#section-4.3) namely, `GET`, `HEAD`, and `POST`. `POST` support is only intended for read-only URLs, such as submitting a search.
+- `request_body` (String) The request body as a string.
+- `request_headers` (Map of String) A map of request header field names and values.
+- `request_timeout_ms` (Number) The request timeout in milliseconds.
+- `retry` (Block, Optional) Retry request configuration. By default there are no retries. Configuring this block will result in retries if an error is returned by the client (e.g., connection errors) or if a 5xx-range (except 501) status code is received. For further details see [go-retryablehttp](https://pkg.go.dev/github.com/hashicorp/go-retryablehttp). (see [below for nested schema](#nestedblock--retry))
+- `when` (String) When to send the HTTP request. Valid values are `apply` (default) and `destroy`. When set to `apply`, the request is sent during resource creation and updates. When set to `destroy`, the request is only sent during resource destruction.
+
+### Read-Only
+
+- `body` (String, Deprecated) The response body returned as a string. **NOTE**: This is deprecated, use `response_body` instead.
+- `id` (String) The URL used for the request.
+- `response_body` (String) The response body returned as a string.
+- `response_body_base64` (String) The response body encoded as base64 (standard) as defined in [RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648#section-4).
+- `response_headers` (Map of String) A map of response header field names and values. Duplicate headers are concatenated according to [RFC2616](https://www.rfc-editor.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2).
+- `status_code` (Number) The HTTP response status code.
+
+<a id="nestedblock--retry"></a>
+### Nested Schema for `retry`
+
+Optional:
+
+- `attempts` (Number) The number of times the request is to be retried. For example, if 2 is specified, the request will be tried a maximum of 3 times.
+- `max_delay_ms` (Number) The maximum delay between retry requests in milliseconds.
+- `min_delay_ms` (Number) The minimum delay between retry requests in milliseconds.
+<!-- cache-key: cdktf-0.20.8 input-resource-http-py -->
+
+