### API Resource Inclusion Mechanism Source: https://developer.hashicorp.com/terraform/enterprise/v202501-1/api-docs Explains how to use the `include` query parameter in GET requests to fetch additional nested resources. These related resources will appear in an `included` section of the API response. ```APIDOC Mechanism: Use 'include' query parameter with a comma-separated list of resource types. Location: Related resources appear in an 'included' section of the response. Availability: Options listed in each endpoint's documentation where available. ``` -------------------------------- ### Example API Response with Pagination Links and Meta Source: https://developer.hashicorp.com/terraform/enterprise/v202501-1/api-docs Illustrates the structure of an API response when pagination is applied, including `links` for navigation (self, first, prev, next, last) and `meta` for pagination details like current page, total pages, and total count. ```json { "data": [...], "links": { "self": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20", "first": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20", "prev": null, "next": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=2&page%5Bsize%5D=20", "last": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=2&page%5Bsize%5D=20" }, "meta": { "pagination": { "current-page": 1, "prev-page": null, "next-page": 2, "total-pages": 2, "total-count": 21 } } } ``` -------------------------------- ### cURL Command to Include Related Resources Source: https://developer.hashicorp.com/terraform/enterprise/v202501-1/api-docs Demonstrates how to use the `include` query parameter in a GET request via cURL to fetch related resources, specifically users associated with a team, by appending `?include=users` to the endpoint URL. ```shell $ curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request GET \ https://app.terraform.io/api/v2/teams/team-n8UQ6wfhyym25sMe?include=users ``` -------------------------------- ### Example JSON API Request Payload for Variables Source: https://developer.hashicorp.com/terraform/enterprise/v202501-1/api-docs This snippet illustrates a typical JSON API document structure used as a request payload for POST methods in the HCP Terraform API. It demonstrates how to define a new variable, including its key, value, category, and sensitivity, along with its relationship to a specific workspace. This structure adheres to the JSON API specification, requiring a top-level `data` property with `type`, `attributes`, and `relationships`. ```JSON { "data": { "type":"vars", "attributes": { "key":"some_key", "value":"some_value", "category":"terraform", "hcl":false, "sensitive":false }, "relationships": { "workspace": { "data": { "id":"ws-4j8p6jX1w33MiDC7", "type":"workspaces" } } } } } ``` -------------------------------- ### API Rate Limit Exceeded Error Response Source: https://developer.hashicorp.com/terraform/enterprise/v202501-1/api-docs Example of a JSON API error object returned when the rate limit is exceeded, indicating a 429 Too Many Requests HTTP status code with a descriptive detail and title. ```json { "errors": [ { "detail": "You have exceeded the API's rate limit.", "status": 429, "title": "Too many requests" } ] } ``` -------------------------------- ### HCP Terraform API Core Concepts and Data Structures Source: https://developer.hashicorp.com/terraform/enterprise/v202501-1/api-docs This section provides an overview of key concepts for the HCP Terraform API, including versioning, standard paths, and adherence to the JSON API specification. It details common attributes like user limits and VCS integrations, explains HTTP response codes, and outlines the structure of JSON API documents, including required properties like `data`, `type`, `attributes`, and `relationships` for request payloads. It also clarifies how nested objects are documented using dot notation and the handling of query parameters. ```APIDOC HCP Terraform API Documentation: 1. API Attributes: - user-limit: An integer value representing the maximum number of users allowed for the organization. If blank, there is no limit. - vcs-integrations: Allows an organization to connect with a VCS provider and link VCS repositories to workspaces. Affects the OAuth Clients and OAuth Tokens endpoints, and determines whether the `data.attributes.vcs-repo` property can be set for workspaces. 2. Response Codes: - Standard HTTP response codes are returned. - 404 Not Found: Returned for resources a user doesn't have access to, or for resources that don't exist, to avoid revealing resource existence. 3. Versioning: - Current API is version 2, residing under the `/v2` prefix. - Future APIs will increment versions, leaving the `/v1` API intact, though in the future certain features might be deprecated. In that case, ample notice will be provided to migrate to the new API. 4. Paths: - All V2 API endpoints use `/api/v2` as a prefix unless otherwise specified. - Example: If the API endpoint documentation defines the path `/runs` then the full path is `/api/v2/runs`. 5. JSON API Formatting: - Endpoints use the JSON API specification (https://jsonapi.org/). - Key aspects covered: HTTP error codes, error objects, document structure, HTTP request/response headers. 6. JSON API Documents: - Most endpoints return JSON API documents. - POST methods also require a JSON API document as the request payload. - Request object structure: - Always includes a top-level `data` property. - `data` must have a `type` property. - Often has an `attributes` property to specify attributes. - Sometimes has a `relationships` property to specify linked objects. - Dot notation is used to explain the structure of nested objects in documentation. - Example Request Object Properties: - data.type: string, Must be \"vars\". - data.attributes.key: string, The name of the variable. - data.attributes.value: string, The value of the variable. - data.attributes.category: string, Whether this is a Terraform or environment variable. Valid values are \"terraform\" or \"env\". - data.attributes.hcl: bool, default `false`, Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. - data.attributes.sensitive: bool, default `false`, Whether the value is sensitive. If true then the variable is written once and not visible thereafter. - data.relationships.workspace.data.type: string, Must be \"workspaces\". - data.relationships.workspace.data.id: string, The ID of the workspace that owns the variable. 7. Query Parameters: - Some GET endpoints use URL query parameters, in the standard `...path?key1=value1&key2=value2` format. - Characters from JSON objects may need percent-encoding (e.g., `[` becomes `%5B` and `]` becomes `%5D`). - For more about URI structure and query strings, see the specification (RFC 3986) or the Wikipedia page on URIs. ``` -------------------------------- ### HCP Terraform Feature Entitlements and Affected API Endpoints Source: https://developer.hashicorp.com/terraform/enterprise/v202501-1/api-docs Details the various feature entitlements available in HCP Terraform, their purpose, and the specific API endpoints that are affected by each entitlement. Lack of an entitlement results in a 404 API error. ```APIDOC Entitlement: agents Description: Allows isolated, private or on-premises infrastructure to communicate with an organization in HCP Terraform. Affected Endpoints: - /terraform/enterprise/api-docs/agents (agent pools) - /terraform/enterprise/api-docs/agents (agents) - /terraform/enterprise/api-docs/agent-tokens (agent tokens) Entitlement: configuration-designer Description: Allows an organization to use the Configuration Designer. Entitlement: cost-estimation Description: Allows an organization to access cost estimation. Entitlement: global-run-tasks Description: Allows an organization to apply run tasks to every workspace. (Beta) Affected Endpoints: - /terraform/enterprise/api-docs/run-tasks/run-tasks Entitlement: module-tests-generation Description: Allows an organization to generate tests for private registry modules. (Beta) Entitlement: operations Description: Allows an organization to perform runs within HCP Terraform. Affected Endpoints: - /terraform/enterprise/api-docs/run (runs) - /terraform/enterprise/api-docs/plans (plans) - /terraform/enterprise/api-docs/applies (applies) Entitlement: policy-enforcement Description: Allows an organization to use Sentinel. Affected Endpoints: - /terraform/enterprise/api-docs/policies (policies) - /terraform/enterprise/api-docs/policy-sets (policy sets) - /terraform/enterprise/api-docs/policy-checks (policy checks) Entitlement: private-module-registry Description: Allows an organization to publish and use modules with the private module registry. Affected Endpoints: - /terraform/enterprise/api-docs/private-registry/modules (registry modules) Entitlement: private-policy-agents Description: Allows an organization to ensure that HTTP enabled Sentinel and OPA policies can communicate with isolated, private, or on-premises infrastructure. Entitlement: run-tasks Description: Allows an organization to use run tasks. Affected Endpoints: - /terraform/enterprise/api-docs/run-tasks/run-tasks Entitlement: self-serve-billing Description: Allows an organization to pay via credit card using the in-app billing UI. Entitlement: sentinel Description: DEPRECATED. Use policy-enforcement instead. Entitlement: state-storage Description: Allows an organization to store state versions in its workspaces, which enables local Terraform runs with HCP Terraform. Affected Endpoints: - /terraform/enterprise/api-docs/state-versions (state versions) Entitlement: sso Description: Allows an organization to manage and authenticate users with single sign on. Entitlement: teams Description: Allows an organization to manage access to its workspaces with teams. Without this entitlement, an organization only has an owners team. Affected Endpoints: - /terraform/enterprise/api-docs/teams (teams) - /terraform/enterprise/api-docs/team-members (team members) - /terraform/enterprise/api-docs/team-access (team access) - /terraform/enterprise/api-docs/team-tokens (team tokens) API Endpoint Reference: show entitlement set: /terraform/enterprise/v202501-1/api-docs/organizations#show-the-entitlement-set Description: Returns information about an organization's current entitlements. ``` -------------------------------- ### API Response with Included Related Resources Source: https://developer.hashicorp.com/terraform/enterprise/v202501-1/api-docs Shows an API response where related resources (users) are included in a separate `included` array at the top level, alongside the primary resource data, demonstrating the effect of the `include` query parameter. ```json { "data": { "id": "team-n8UQ6wfhyym25sMe", "type": "teams", "attributes": { "name": "owners", "users-count": 1 ... }, "relationships": { "users": { "data": [ { "id": "user-62goNpx1ThQf689e", "type": "users" } ] } ... } ... }, "included": [ { "id": "user-62goNpx1ThQf689e", "type": "users", "attributes": { "username": "hashibot" ... } ... } ] } ``` -------------------------------- ### API Pagination Query Parameters Source: https://developer.hashicorp.com/terraform/enterprise/v202501-1/api-docs Details the optional query parameters `page[number]` and `page[size]` used to control pagination on list endpoints, including their default behaviors and maximum page size. It also notes where additional pagination data is returned in the response. ```APIDOC Parameter: page[number] Description: Optional. If omitted, the endpoint will return the first page. Parameter: page[size] Description: Optional. If omitted, the endpoint will return 20 items per page. The maximum page size is 100. Additional Data: Returned in 'links' and 'meta' top-level attributes of the response. ``` -------------------------------- ### API Rate Limiting Policy Source: https://developer.hashicorp.com/terraform/enterprise/v202501-1/api-docs Describes the API's rate limit of 30 requests per second for authenticated and unauthenticated requests. It explains how limits are applied, notes lower limits for specific endpoints, and mentions the `x-ratelimit-limit` header for indicating throttling. ```APIDOC Limit: Up to 30 requests per second (authenticated or unauthenticated). Throttling: Access throttled, error response returned if limit reached. Lower Limits: Some endpoints have lower rate limits (e.g., polling runs, user authentication). Authenticated Requests: Allocated to the user associated with the authentication token. Multiple tokens do not increase the limit. Unauthenticated Requests: Associated with the requesting IP address. Response Header: 'x-ratelimit-limit' header reflects the limit once triggered. Status Code: 429 Too Many Requests Response: JSON API error object Reason: Rate limit has been reached. ``` -------------------------------- ### HCP Terraform API Authentication Methods Source: https://developer.hashicorp.com/terraform/enterprise/v202501-1/api-docs This section details the required authentication method for all HCP Terraform API requests, which involves using a bearer token in the `Authorization` HTTP header. It explains the different types of tokens available—user, team, and organization tokens—outlining their respective use cases, permissions, and limitations. ```APIDOC Authentication: Method: Bearer Token Header: Authorization: Bearer Error Handling: - HTTP Status 401: Token absent or invalid (JSON API error object) - HTTP Status 404: Forbidden request with a valid token Token Types: - User Tokens: - Purpose: Make requests on behalf of an HCP Terraform user. - Details: Each user can have multiple API tokens. - Team Tokens: - Purpose: Perform plans and applies via a CI/CD pipeline. - Details: Each team can have one API token at a time. - Organization Tokens: - Purpose: Automate management of teams, team membership, and workspaces. - Limitations: Cannot perform plans and applies. - Details: Each organization can have one API token at a time. ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.