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`.