A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://developer.hashicorp.com/terraform/registry/api-docs below:

Registry API for the Terraform registry | Terraform

When downloading modules from registry sources such as the public Terraform Registry, Terraform CLI expects the given hostname to support the module registry protocol, which is the minimal API required for Terraform CLI to successfully retrieve a module.

The public Terraform Registry and the private registry included in HCP Terraform and Terraform Enterprise implement a superset of that minimal module registry API to support additional use-cases such as searching for modules across the whole registry, retrieving documentation and schemas for modules, and so on.

This page describes the extended API implemented by the official module registry implementations, and is aimed at those intending to build clients to work with registry data. Third-party implementations of the registry protocol are not required to implement these extensions. If you intend to implement your own module registry, please refer to the module registry protocol instead.

Terraform Registry also has some additional internal API endpoints used to support its UI. Any endpoints or properties not documented on this page are subject to change over time.

The hostname portion of a module source address is first passed to the service discovery protocol to determine if the given host has a module registry and, if so, the base URL for its module registry endpoints.

The service identifier for this protocol is modules.v1, and the declared URL should always end with a slash such that the paths shown in the following sections can be appended to it.

For example, if discovery produces the URL https://modules.example.com/v1/ then this API would use full endpoint URLs like https://modules.example.com/v1/{namespace}/{name}/{provider}/versions.

A module source address with no hostname is a shorthand for an address on registry.terraform.io. You can perform service discovery on that hostname to find the public Terraform Registry's module API endpoints.

The example request URLs shown in this document are for the public Terraform Registry, and use its API <base_url> of https://registry.terraform.io/v1/modules/. Note that although the base URL in the discovery document may include a trailing slash, we include a slash after the placeholder in the Paths below for clarity.

These endpoints list modules according to some criteria.

Method Path Produces GET <base_url> application/json GET <base_url>/:namespace application/json Parameters Query Parameters Sample Request 
$ curl 'https://registry.terraform.io/v1/modules?limit=2&verified=true'
Sample Response 
{
  "meta": {
    "limit": 2,
    "current_offset": 0,
    "next_offset": 2,
    "next_url": "/v1/modules?limit=2&offset=2&verified=true"
  },
  "modules": [
    {
      "id": "GoogleCloudPlatform/lb-http/google/1.0.4",
      "owner": "",
      "namespace": "GoogleCloudPlatform",
      "name": "lb-http",
      "version": "1.0.4",
      "provider": "google",
      "description": "Modular Global HTTP Load Balancer for GCE using forwarding rules.",
      "source": "https://github.com/GoogleCloudPlatform/terraform-google-lb-http",
      "published_at": "2017-10-17T01:22:17.792066Z",
      "downloads": 213,
      "verified": true
    },
    {
      "id": "terraform-aws-modules/vpc/aws/1.5.1",
      "owner": "",
      "namespace": "terraform-aws-modules",
      "name": "vpc",
      "version": "1.5.1",
      "provider": "aws",
      "description": "Terraform module which creates VPC resources on AWS",
      "source": "https://github.com/terraform-aws-modules/terraform-aws-vpc",
      "published_at": "2017-11-23T10:48:09.400166Z",
      "downloads": 29714,
      "verified": true
    }
  ]
}

This endpoint allows searching modules.

Method Path Produces GET <base_url>/search application/json Query Parameters Sample Request 
$ curl 'https://registry.terraform.io/v1/modules/search?q=network&limit=2'
Sample Response 
{
  "meta": {
    "limit": 2,
    "current_offset": 0,
    "next_offset": 2,
    "next_url": "/v1/modules/search?limit=2&offset=2&q=network"
  },
  "modules": [
    {
      "id": "zoitech/network/aws/0.0.3",
      "owner": "",
      "namespace": "zoitech",
      "name": "network",
      "version": "0.0.3",
      "provider": "aws",
      "description": "This module is intended to be used for configuring an AWS network.",
      "source": "https://github.com/zoitech/terraform-aws-network",
      "published_at": "2017-11-23T15:12:06.620059Z",
      "downloads": 39,
      "verified": false
    },
    {
      "id": "Azure/network/azurerm/1.1.1",
      "owner": "",
      "namespace": "Azure",
      "name": "network",
      "version": "1.1.1",
      "provider": "azurerm",
      "description": "Terraform Azure RM Module for Network",
      "source": "https://github.com/Azure/terraform-azurerm-network",
      "published_at": "2017-11-22T17:15:34.325436Z",
      "downloads": 1033,
      "verified": true
    }
  ]
}

This is the primary endpoint for resolving module sources, returning the available versions for a given fully-qualified module.

Method Path Produces GET <base_url>/:namespace/:name/:provider/versions application/json Parameters Sample Request 
$ curl https://registry.terraform.io/v1/modules/hashicorp/consul/aws/versions
Sample Response

The modules array in the response always includes the requested module as the first element. Other elements of this list, if present, are dependencies of the requested module that are provided to potentially avoid additional requests to resolve these modules.

Additional modules are not required to be provided but, when present, can be used by Terraform to optimize the module installation process.

Each returned module has an array of available versions, which Terraform matches against any version constraints given in configuration.

{
   "modules": [
      {
         "source": "hashicorp/consul/aws",
         "versions": [
            {
               "version": "0.0.1",
               "submodules" : [
                  {
                     "path": "modules/consul-cluster",
                     "providers": [
                        {
                           "name": "aws",
                           "version": ""
                        }
                     ],
                     "dependencies": []
                  },
                  {
                     "path": "modules/consul-security-group-rules",
                     "providers": [
                        {
                           "name": "aws",
                           "version": ""
                        }
                     ],
                     "dependencies": []
                  },
                  {
                     "providers": [
                        {
                           "name": "aws",
                           "version": ""
                        }
                     ],
                     "dependencies": [],
                     "path": "modules/consul-iam-policies"
                  }
               ],
               "root": {
                  "dependencies": [],
                  "providers": [
                     {
                        "name": "template",
                        "version": ""
                     },
                     {
                        "name": "aws",
                        "version": ""
                     }
                  ]
               }
            }
         ]
      }
   ]
}

This endpoint downloads the specified version of a module for a single provider.

A successful response has no body, and includes the location from which the module version's source can be downloaded in the X-Terraform-Get header. Note that this string may contain special syntax interpreted by Terraform via go-getter. See the go-getter documentation for details.

The value of X-Terraform-Get may instead be a relative URL, indicated by beginning with /, ./ or ../, in which case it is resolved relative to the full URL of the download endpoint.

Method Path Produces GET <base_url>/:namespace/:name/:provider/:version/download application/json Parameters Sample Request 
$ curl -i \
    https://registry.terraform.io/v1/modules/hashicorp/consul/aws/0.0.1/download
Sample Response 
HTTP/1.1 204 No Content
Content-Length: 0
X-Terraform-Get: https://api.github.com/repos/hashicorp/terraform-aws-consul/tarball/v0.0.1//*?archive=tar.gz

This endpoint returns the latest version of each provider for a module.

Method Path Produces GET <base_url>/:namespace/:name application/json Parameters Query Parameters Sample Request 
$ curl \
    https://registry.terraform.io/v1/modules/hashicorp/consul
Sample Response 
{
  "meta": {
    "limit": 15,
    "current_offset": 0
  },
  "modules": [
    {
      "id": "hashicorp/consul/azurerm/0.0.1",
      "owner": "gruntwork-team",
      "namespace": "hashicorp",
      "name": "consul",
      "version": "0.0.1",
      "provider": "azurerm",
      "description": "A Terraform Module for how to run Consul on AzureRM using Terraform and Packer",
      "source": "https://github.com/hashicorp/terraform-azurerm-consul",
      "published_at": "2017-09-14T23:22:59.923047Z",
      "downloads": 100,
      "verified": false
    },
    {
      "id": "hashicorp/consul/aws/0.0.1",
      "owner": "gruntwork-team",
      "namespace": "hashicorp",
      "name": "consul",
      "version": "0.0.1",
      "provider": "aws",
      "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer",
      "source": "https://github.com/hashicorp/terraform-aws-consul",
      "published_at": "2017-09-14T23:22:44.793647Z",
      "downloads": 113,
      "verified": false
    }
  ]
}

This endpoint returns the latest version of a module for a single provider.

Method Path Produces GET <base_url>/:namespace/:name/:provider application/json Parameters Sample Request 
$ curl \
    https://registry.terraform.io/v1/modules/hashicorp/consul/aws
Sample Response

Note this response has has some fields trimmed for clarity.

{
  "id": "hashicorp/consul/aws/0.0.1",
  "owner": "gruntwork-team",
  "namespace": "hashicorp",
  "name": "consul",
  "version": "0.0.1",
  "provider": "aws",
  "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer",
  "source": "https://github.com/hashicorp/terraform-aws-consul",
  "published_at": "2017-09-14T23:22:44.793647Z",
  "downloads": 113,
  "verified": false,
  "root": {
    "path": "",
    "readme": "# Consul AWS Module\n\nThis repo contains a Module for how to deploy a [Consul]...",
    "empty": false,
    "inputs": [
      {
        "name": "ami_id",
        "description": "The ID of the AMI to run in the cluster. ...",
        "default": "\"\""
      },
      {
        "name": "aws_region",
        "description": "The AWS region to deploy into (e.g. us-east-1).",
        "default": "\"us-east-1\""
      }
    ],
    "outputs": [
      {
        "name": "num_servers",
        "description": ""
      },
      {
        "name": "asg_name_servers",
        "description": ""
      }
    ],
    "dependencies": [],
    "resources": []
  },
  "submodules": [
    {
      "path": "modules/consul-cluster",
      "readme": "# Consul Cluster\n\nThis folder contains a [Terraform](https://www.terraform.io/) ...",
      "empty": false,
      "inputs": [
        {
          "name": "cluster_name",
          "description": "The name of the Consul cluster (e.g. consul-stage). This variable is used to namespace all resources created by this module.",
          "default": ""
        },
        {
          "name": "ami_id",
          "description": "The ID of the AMI to run in this cluster. Should be an AMI that had Consul installed and configured by the install-consul module.",
          "default": ""
        }
      ],
      "outputs": [
        {
          "name": "asg_name",
          "description": ""
        },
        {
          "name": "cluster_size",
          "description": ""
        }
      ],
      "dependencies": [],
      "resources": [
        {
          "name": "autoscaling_group",
          "type": "aws_autoscaling_group"
        },
        {
          "name": "launch_configuration",
          "type": "aws_launch_configuration"
        }
      ]
    }
  ],
  "providers": [
    "aws",
    "azurerm"
  ],
  "versions": [
    "0.0.1"
  ]
}

This endpoint returns the specified version of a module for a single provider.

Method Path Produces GET <base_url>/:namespace/:name/:provider/:version application/json Parameters Sample Request 
$ curl \
    https://registry.terraform.io/v1/modules/hashicorp/consul/aws/0.0.1
Sample Response

Note this response has has some fields trimmed for clarity.

{
  "id": "hashicorp/consul/aws/0.0.1",
  "owner": "gruntwork-team",
  "namespace": "hashicorp",
  "name": "consul",
  "version": "0.0.1",
  "provider": "aws",
  "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer",
  "source": "https://github.com/hashicorp/terraform-aws-consul",
  "published_at": "2017-09-14T23:22:44.793647Z",
  "downloads": 113,
  "verified": false,
  "root": {
    "path": "",
    "readme": "# Consul AWS Module\n\nThis repo contains a Module for how to deploy a [Consul]...",
    "empty": false,
    "inputs": [
      {
        "name": "ami_id",
        "description": "The ID of the AMI to run in the cluster. ...",
        "default": "\"\""
      },
      {
        "name": "aws_region",
        "description": "The AWS region to deploy into (e.g. us-east-1).",
        "default": "\"us-east-1\""
      }
    ],
    "outputs": [
      {
        "name": "num_servers",
        "description": ""
      },
      {
        "name": "asg_name_servers",
        "description": ""
      }
    ],
    "dependencies": [],
    "resources": []
  },
  "submodules": [
    {
      "path": "modules/consul-cluster",
      "readme": "# Consul Cluster\n\nThis folder contains a [Terraform](https://www.terraform.io/) ...",
      "empty": false,
      "inputs": [
        {
          "name": "cluster_name",
          "description": "The name of the Consul cluster (e.g. consul-stage). This variable is used to namespace all resources created by this module.",
          "default": ""
        },
        {
          "name": "ami_id",
          "description": "The ID of the AMI to run in this cluster. Should be an AMI that had Consul installed and configured by the install-consul module.",
          "default": ""
        }
      ],
      "outputs": [
        {
          "name": "asg_name",
          "description": ""
        },
        {
          "name": "cluster_size",
          "description": ""
        }
      ],
      "dependencies": [],
      "resources": [
        {
          "name": "autoscaling_group",
          "type": "aws_autoscaling_group"
        },
        {
          "name": "launch_configuration",
          "type": "aws_launch_configuration"
        }
      ]
    }
  ],
  "providers": [
    "aws",
    "azurerm"
  ],
  "versions": [
    "0.0.1"
  ]
}

This endpoint downloads the latest version of a module for a single provider.

It returns a 302 redirect whose Location header redirects the client to the download endpoint (above) for the latest version.

Method Path Produces GET <base_url>/:namespace/:name/:provider/download application/json Parameters Sample Request 
$ curl -i \
    https://registry.terraform.io/v1/modules/hashicorp/consul/aws/download
Sample Response 
HTTP/1.1 302 Found
Location: /v1/modules/hashicorp/consul/aws/0.0.1/download
Content-Length: 70
Content-Type: text/html; charset=utf-8

<a href="/v1/modules/hashicorp/consul/aws/0.0.1/download">Found</a>.

Note: The download metrics summary APIs are v2and use the API <base_url> of https://registry.terraform.io/v2/modules/

This endpoint returns a module's download metrics summary.

Method Path Produces GET <base_url>/:namespace/:name/:provider/downloads/summary application/json Parameters Sample Request 
$ curl \
    https://registry.terraform.io/v2/modules/hashicorp/consul/aws/downloads/summary
Sample Response 
"data": {
    "type": "module-downloads-summary",
    "id": "5792",
    "attributes": {
      "week": 645,
      "month": 2474,
      "year": 8621,
      "total": 90237
    }
  }

The API follows regular HTTP status semantics. To make implementing a complete client easier, some details on our policy and potential future status codes are listed below. A robust client should consider how to handle all of the following.

When a 4xx or 5xx status code is returned. The response payload will look like the following example:

{
  "errors": [
    "something bad happened"
  ]
}

The errors key is a list containing one or more strings where each string describes an error that has occurred.

Note that it is possible that some 5xx errors might result in a response that is not in JSON format above due to being returned by an intermediate proxy.

Pagination

Endpoints that return lists of results use a common pagination format.

They accept positive integer query variables offset and limit which have the usual SQL-like semantics. Each endpoint will have a default limit and a default offset of 0. Each endpoint will also apply a maximum limit, requesting more results will just result in the maximum limit being used.

The response for a paginated result set will look like:

{
  "meta": {
    "limit": 15,
    "current_offset": 15,
    "next_offset": 30,
    "prev_offset": 0,
  },
  "<object name>": []
}

Note that:

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4