github.com/trawler/terraform@v0.10.8-0.20171106022149-4b1c7a1d9b48/website/docs/registry/api.html.md (about)

     1  ---
     2  layout: "registry"
     3  page_title: "Terraform Registry - HTTP API"
     4  sidebar_current: "docs-registry-api"
     5  description: |-
     6    The /acl endpoints create, update, destroy, and query ACL tokens in Consul.
     7  ---
     8  
     9  # HTTP API
    10  
    11  When downloading modules from registry sources such as the public
    12  [Terraform Registry](https://registry.terraform.io), Terraform expects
    13  the given hostname to support the following module registry protocol.
    14  
    15  A registry module source is of the form `hostname/namespace/name/provider`,
    16  where the initial hostname portion is implied to be `registry.terraform.io/`
    17  if not specified. The public Terraform Registry is therefore the default
    18  module source.
    19  
    20  [Terraform Registry](https://registry.terraform.io) implements a superset
    21  of this API to allow for importing new modules, etc, but any endpoints not
    22  documented on this page are subject to change over time.
    23  
    24  ## Service Discovery
    25  
    26  The hostname portion of a module source string is first passed to
    27  [the service discovery protocol](/docs/internals/remote-service-discovery.html)
    28  to determine if the given host has a module registry and, if so, the base
    29  URL for its module registry endpoints.
    30  
    31  The service identifier for this protocol is `modules.v1`, and the declared
    32  URL should always end with a slash such that the paths shown in the following
    33  sections can be appended to it.
    34  
    35  For example, if discovery produces the URL `https://modules.example.com/v1/`
    36  then this API would use full endpoint URLs like
    37  `https://modules.example.com/v1/{namespace}/{name}/{provider}/versions`.
    38  
    39  The example request URLs shown in this document are for the public
    40  [Terraform Registry](https://registry.terraform.io), and use its API base
    41  URL of `https://registry.terraform.io/v1/modules/` .
    42  
    43  ## List Available Versions for a Specific Module
    44  
    45  This is the primary endpoint for resolving module sources, returning the
    46  available versions for a given fully-qualified module.
    47  
    48  | Method | Path                                  | Produces                   |
    49  | ------ | ------------------------------------- | -------------------------- |
    50  | `GET`  | `:namespace/:name/:provider/versions` | `application/json`         |
    51  
    52  ### Parameters
    53  
    54  - `namespace` `(string: <required>)` - The user or organization the module is
    55    owned by. This is required and is specified as part of the URL path.
    56  
    57  - `name` `(string: <required>)` - The name of the module.
    58    This is required and is specified as part of the URL path.
    59  
    60  - `provider` `(string: <required>)` - The name of the provider.
    61    This is required and is specified as part of the URL path.
    62  
    63  ### Sample Request
    64  
    65  ```text
    66  $ curl https://registry.terraform.io/v1/modules/hashicorp/consul/aws/versions
    67  ```
    68  
    69  ### Sample Response
    70  
    71  The `modules` array in the response always includes the requested module as the
    72  first element. Other elements of this list, if present, are dependencies of the
    73  requested module that are provided to potentially avoid additional requests to
    74  resolve these modules.
    75  
    76  Additional modules are not required to be provided but, when present, can be
    77  used by Terraform to optimize the module installation process.
    78  
    79  Each returned module has an array of available versions, which Terraform
    80  matches against any version constraints given in configuration.
    81  
    82  ```json
    83  {
    84     "modules": [
    85        {
    86           "source": "hashicorp/consul/aws",
    87           "versions": [
    88              {
    89                 "version": "0.0.1",
    90                 "submodules" : [
    91                    {
    92                       "path": "modules/consul-cluster",
    93                       "providers": [
    94                          {
    95                             "name": "aws",
    96                             "version": ""
    97                          }
    98                       ],
    99                       "dependencies": []
   100                    },
   101                    {
   102                       "path": "modules/consul-security-group-rules",
   103                       "providers": [
   104                          {
   105                             "name": "aws",
   106                             "version": ""
   107                          }
   108                       ],
   109                       "dependencies": []
   110                    },
   111                    {
   112                       "providers": [
   113                          {
   114                             "name": "aws",
   115                             "version": ""
   116                          }
   117                       ],
   118                       "dependencies": [],
   119                       "path": "modules/consul-iam-policies"
   120                    }
   121                 ],
   122                 "root": {
   123                    "dependencies": [],
   124                    "providers": [
   125                       {
   126                          "name": "template",
   127                          "version": ""
   128                       },
   129                       {
   130                          "name": "aws",
   131                          "version": ""
   132                       }
   133                    ]
   134                 }
   135              }
   136           ]
   137        }
   138     ]
   139  }
   140  ```
   141  
   142  ## Download Source Code for a Specific Module Version
   143  
   144  This endpoint downloads the specified version of a module for a single provider.
   145  
   146  A successful response has no body, and includes the location from which the module
   147  version's source can be downloaded in the `X-Terraform-Get` header. Note that
   148  this string may contain special syntax interpreted by Terraform via
   149  [`go-getter`](https://github.com/hashicorp/go-getter). See the [`go-getter`
   150  documentation](https://github.com/hashicorp/go-getter#url-format) for details.
   151  
   152  The value of `X-Terraform-Get` may instead be a relative URL, indicated by
   153  beginning with `/`, `./` or `../`, in which case it is resolved relative to
   154  the full URL of the download endpoint.
   155  
   156  | Method | Path                         | Produces                   |
   157  | ------ | ---------------------------- | -------------------------- |
   158  | `GET`  | `:namespace/:name/:provider/:version/download` | `application/json`         |
   159  
   160  ### Parameters
   161  
   162  - `namespace` `(string: <required>)` - The user the module is owned by.
   163    This is required and is specified as part of the URL path.
   164  
   165  - `name` `(string: <required>)` - The name of the module.
   166    This is required and is specified as part of the URL path.
   167  
   168  - `provider` `(string: <required>)` - The name of the provider.
   169    This is required and is specified as part of the URL path.
   170  
   171  - `version` `(string: <required>)` - The version of the module.
   172    This is required and is specified as part of the URL path.
   173  
   174  ### Sample Request
   175  
   176  ```text
   177  $ curl -i \
   178      https://registry.terraform.io/v1/modules/hashicorp/consul/aws/0.0.1/download
   179  ```
   180  
   181  ### Sample Response
   182  
   183  ```text
   184  HTTP/1.1 204 No Content
   185  Content-Length: 0
   186  X-Terraform-Get: https://api.github.com/repos/hashicorp/terraform-aws-consul/tarball/v0.0.1//*?archive=tar.gz
   187  ```
   188  
   189  ## List Latest Version of Module for All Providers
   190  
   191  This endpoint returns the latest version of each provider for a module.
   192  
   193  | Method | Path                         | Produces                   |
   194  | ------ | ---------------------------- | -------------------------- |
   195  | `GET`  | `:namespace/:name`           | `application/json`         |
   196  
   197  ### Parameters
   198  
   199  - `namespace` `(string: <required>)` - The user or organization the module is
   200    owned by. This is required and is specified as part of the URL path.
   201  
   202  - `name` `(string: <required>)` - The name of the module.
   203    This is required and is specified as part of the URL path.
   204  
   205  ### Query Parameters
   206  
   207  - `offset`, `limit` `(int: <optional>)` - See [Pagination](#Pagination) for details.
   208  
   209  ### Sample Request
   210  
   211  ```text
   212  $ curl \
   213      https://registry.terraform.io/v1/modules/hashicorp/consul
   214  ```
   215  
   216  ### Sample Response
   217  
   218  ```json
   219  {
   220    "meta": {
   221      "limit": 15,
   222      "current_offset": 0
   223    },
   224    "modules": [
   225      {
   226        "id": "hashicorp/consul/azurerm/0.0.1",
   227        "owner": "gruntwork-team",
   228        "namespace": "hashicorp",
   229        "name": "consul",
   230        "version": "0.0.1",
   231        "provider": "azurerm",
   232        "description": "A Terraform Module for how to run Consul on AzureRM using Terraform and Packer",
   233        "source": "https://github.com/hashicorp/terraform-azurerm-consul",
   234        "published_at": "2017-09-14T23:22:59.923047Z",
   235        "downloads": 100,
   236        "verified": false
   237      },
   238      {
   239        "id": "hashicorp/consul/aws/0.0.1",
   240        "owner": "gruntwork-team",
   241        "namespace": "hashicorp",
   242        "name": "consul",
   243        "version": "0.0.1",
   244        "provider": "aws",
   245        "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer",
   246        "source": "https://github.com/hashicorp/terraform-aws-consul",
   247        "published_at": "2017-09-14T23:22:44.793647Z",
   248        "downloads": 113,
   249        "verified": false
   250      }
   251    ]
   252  }
   253  ```
   254  
   255  ## Latest Version for a Specific Module Provider
   256  
   257  This endpoint returns the latest version of a module for a single provider.
   258  
   259  | Method | Path                         | Produces                   |
   260  | ------ | ---------------------------- | -------------------------- |
   261  | `GET`  | `:namespace/:name/:provider` | `application/json`         |
   262  
   263  ### Parameters
   264  
   265  - `namespace` `(string: <required>)` - The user the module is owned by.
   266    This is required and is specified as part of the URL path.
   267  
   268  - `name` `(string: <required>)` - The name of the module.
   269    This is required and is specified as part of the URL path.
   270  
   271  - `provider` `(string: <required>)` - The name of the provider.
   272    This is required and is specified as part of the URL path.
   273  
   274  ### Sample Request
   275  
   276  ```text
   277  $ curl \
   278      https://registry.terraform.io/v1/modules/hashicorp/consul/aws
   279  ```
   280  
   281  ### Sample Response
   282  
   283  Note this response has has some fields trimmed for clarity.
   284  
   285  ```json
   286  {
   287    "id": "hashicorp/consul/aws/0.0.1",
   288    "owner": "gruntwork-team",
   289    "namespace": "hashicorp",
   290    "name": "consul",
   291    "version": "0.0.1",
   292    "provider": "aws",
   293    "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer",
   294    "source": "https://github.com/hashicorp/terraform-aws-consul",
   295    "published_at": "2017-09-14T23:22:44.793647Z",
   296    "downloads": 113,
   297    "verified": false,
   298    "root": {
   299      "path": "",
   300      "readme": "# Consul AWS Module\n\nThis repo contains a Module for how to deploy a [Consul]...",
   301      "empty": false,
   302      "inputs": [
   303        {
   304          "name": "ami_id",
   305          "description": "The ID of the AMI to run in the cluster. ...",
   306          "default": "\"\""
   307        },
   308        {
   309          "name": "aws_region",
   310          "description": "The AWS region to deploy into (e.g. us-east-1).",
   311          "default": "\"us-east-1\""
   312        }
   313      ],
   314      "outputs": [
   315        {
   316          "name": "num_servers",
   317          "description": ""
   318        },
   319        {
   320          "name": "asg_name_servers",
   321          "description": ""
   322        }
   323      ],
   324      "dependencies": [],
   325      "resources": []
   326    },
   327    "submodules": [
   328      {
   329        "path": "modules/consul-cluster",
   330        "readme": "# Consul Cluster\n\nThis folder contains a [Terraform](https://www.terraform.io/) ...",
   331        "empty": false,
   332        "inputs": [
   333          {
   334            "name": "cluster_name",
   335            "description": "The name of the Consul cluster (e.g. consul-stage). This variable is used to namespace all resources created by this module.",
   336            "default": ""
   337          },
   338          {
   339            "name": "ami_id",
   340            "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.",
   341            "default": ""
   342          }
   343        ],
   344        "outputs": [
   345          {
   346            "name": "asg_name",
   347            "description": ""
   348          },
   349          {
   350            "name": "cluster_size",
   351            "description": ""
   352          }
   353        ],
   354        "dependencies": [],
   355        "resources": [
   356          {
   357            "name": "autoscaling_group",
   358            "type": "aws_autoscaling_group"
   359          },
   360          {
   361            "name": "launch_configuration",
   362            "type": "aws_launch_configuration"
   363          }
   364        ]
   365      }
   366    ],
   367    "providers": [
   368      "aws",
   369      "azurerm"
   370    ],
   371    "versions": [
   372      "0.0.1"
   373    ]
   374  }
   375  ```
   376  
   377  ## Get a Specific Module
   378  
   379  This endpoint returns the specified version of a module for a single provider.
   380  
   381  | Method | Path                         | Produces                   |
   382  | ------ | ---------------------------- | -------------------------- |
   383  | `GET`  | `:namespace/:name/:provider/:version` | `application/json`         |
   384  
   385  ### Parameters
   386  
   387  - `namespace` `(string: <required>)` - The user the module is owned by.
   388    This is required and is specified as part of the URL path.
   389  
   390  - `name` `(string: <required>)` - The name of the module.
   391    This is required and is specified as part of the URL path.
   392  
   393  - `provider` `(string: <required>)` - The name of the provider.
   394    This is required and is specified as part of the URL path.
   395  
   396  - `version` `(string: <required>)` - The version of the module.
   397    This is required and is specified as part of the URL path.
   398  
   399  ### Sample Request
   400  
   401  ```text
   402  $ curl \
   403      https://registry.terraform.io/v1/modules/hashicorp/consul/aws/0.0.1
   404  ```
   405  
   406  ### Sample Response
   407  
   408  Note this response has has some fields trimmed for clarity.
   409  
   410  
   411  ```json
   412  {
   413    "id": "hashicorp/consul/aws/0.0.1",
   414    "owner": "gruntwork-team",
   415    "namespace": "hashicorp",
   416    "name": "consul",
   417    "version": "0.0.1",
   418    "provider": "aws",
   419    "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer",
   420    "source": "https://github.com/hashicorp/terraform-aws-consul",
   421    "published_at": "2017-09-14T23:22:44.793647Z",
   422    "downloads": 113,
   423    "verified": false,
   424    "root": {
   425      "path": "",
   426      "readme": "# Consul AWS Module\n\nThis repo contains a Module for how to deploy a [Consul]...",
   427      "empty": false,
   428      "inputs": [
   429        {
   430          "name": "ami_id",
   431          "description": "The ID of the AMI to run in the cluster. ...",
   432          "default": "\"\""
   433        },
   434        {
   435          "name": "aws_region",
   436          "description": "The AWS region to deploy into (e.g. us-east-1).",
   437          "default": "\"us-east-1\""
   438        }
   439      ],
   440      "outputs": [
   441        {
   442          "name": "num_servers",
   443          "description": ""
   444        },
   445        {
   446          "name": "asg_name_servers",
   447          "description": ""
   448        }
   449      ],
   450      "dependencies": [],
   451      "resources": []
   452    },
   453    "submodules": [
   454      {
   455        "path": "modules/consul-cluster",
   456        "readme": "# Consul Cluster\n\nThis folder contains a [Terraform](https://www.terraform.io/) ...",
   457        "empty": false,
   458        "inputs": [
   459          {
   460            "name": "cluster_name",
   461            "description": "The name of the Consul cluster (e.g. consul-stage). This variable is used to namespace all resources created by this module.",
   462            "default": ""
   463          },
   464          {
   465            "name": "ami_id",
   466            "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.",
   467            "default": ""
   468          }
   469        ],
   470        "outputs": [
   471          {
   472            "name": "asg_name",
   473            "description": ""
   474          },
   475          {
   476            "name": "cluster_size",
   477            "description": ""
   478          }
   479        ],
   480        "dependencies": [],
   481        "resources": [
   482          {
   483            "name": "autoscaling_group",
   484            "type": "aws_autoscaling_group"
   485          },
   486          {
   487            "name": "launch_configuration",
   488            "type": "aws_launch_configuration"
   489          }
   490        ]
   491      }
   492    ],
   493    "providers": [
   494      "aws",
   495      "azurerm"
   496    ],
   497    "versions": [
   498      "0.0.1"
   499    ]
   500  }
   501  ```
   502  
   503  ## Download the Latest Version of a Module
   504  
   505  This endpoint downloads the latest version of a module for a single provider.
   506  
   507  It returns a 302 redirect whose `Location` header redirects the client to the
   508  download endpoint (above) for the latest version.
   509  
   510  | Method | Path                         | Produces                   |
   511  | ------ | ---------------------------- | -------------------------- |
   512  | `GET`  | `:namespace/:name/:provider/download` | `application/json`         |
   513  
   514  ### Parameters
   515  
   516  - `namespace` `(string: <required>)` - The user the module is owned by.
   517    This is required and is specified as part of the URL path.
   518  
   519  - `name` `(string: <required>)` - The name of the module.
   520    This is required and is specified as part of the URL path.
   521  
   522  - `provider` `(string: <required>)` - The name of the provider.
   523    This is required and is specified as part of the URL path.
   524  
   525  - `version` `(string: <required>)` - The version of the module.
   526    This is required and is specified as part of the URL path.
   527  
   528  ### Sample Request
   529  
   530  ```text
   531  $ curl -i \
   532      https://registry.terraform.io/v1/modules/hashicorp/consul/aws/download
   533  ```
   534  
   535  ### Sample Response
   536  
   537  ```text
   538  HTTP/1.1 302 Found
   539  Location: /v1/modules/hashicorp/consul/aws/0.0.1/download
   540  Content-Length: 70
   541  Content-Type: text/html; charset=utf-8
   542  
   543  <a href="/v1/modules/hashicorp/consul/aws/0.0.1/download">Found</a>.
   544  ```
   545  
   546  ## HTTP Status Codes
   547  
   548  The API follows regular HTTP status semantics. To make implementing a complete
   549  client easier, some details on our policy and potential future status codes are
   550  listed below. A robust client should consider how to handle all of the
   551  following.
   552  
   553   - **Success:** Return status is `200` on success with a body or `204` if there
   554     is no body data to return.
   555   - **Redirects:** Moved or aliased endpoints redirect with a `301`. Endpoints
   556     redirecting to the latest version of a module may redirect with `302` or
   557     `307` to indicate that they logically point to different resources over time.
   558   - **Client Errors:** Invalid requests will receive the relevant `4xx` status.
   559     Except where noted below, the request should not be retried.
   560   - **Rate Limiting:** Clients placing excessive load on the service might be
   561     rate-limited and receive a `429` code. This should be interpreted as a sign
   562     to slow down, and wait some time before retrying the request.
   563   - **Service Errors:** The usual `5xx` errors will be returned for service
   564     failures. In all cases it is safe to retry the request after receiving a
   565     `5xx` response.
   566   - **Load Shedding:** A `503` response indicates that the service is under load
   567     and can't process your request immediately. As with other `5xx` errors you
   568     may retry after some delay, although clients should consider being more
   569     lenient with retry schedule in this case.
   570  
   571  ## Error Responses
   572  
   573  When a `4xx` or `5xx` status code is returned. The response payload will look
   574  like the following example:
   575  
   576  ```json
   577  {
   578    "errors": [
   579      "something bad happened"
   580    ]
   581  }
   582  ```
   583  
   584  The `errors` key is a list containing one or more strings where each string
   585  describes an error that has occurred.
   586  
   587  Note that it is possible that some `5xx` errors might result in a response that
   588  is not in JSON format above due to being returned by an intermediate proxy.
   589  
   590  ## Pagination
   591  
   592  Endpoints that return lists of results use a common pagination format.
   593  
   594  They accept positive integer query variables `offset` and `limit` which have the
   595  usual SQL-like semantics. Each endpoint will have a sane default limit and a
   596  default offset of `0`. Each endpoint will also apply a sane maximum limit,
   597  requesting more results will just result in the maximum limit being used.
   598  
   599  The response for a paginated result set will look like:
   600  
   601  ```json
   602  {
   603    "meta": {
   604      "limit": 15,
   605      "current_offset": 15,
   606      "next_offset": 30,
   607      "prev_offset": 0,
   608    },
   609    "<object name>": []
   610  }
   611  ```
   612  Note that:
   613    - `next_offset` will only be present if there are more results available.
   614    - `prev_offset` will only be present if not at `offset = 0`.
   615    - `limit` is the actual limit that was applied, it may be lower than the requested limit param.
   616    - The key for the result array varies based on the endpoint and will be the
   617      type of result pluralized, for example `modules`.