github.com/pdecat/terraform@v0.11.9-beta1/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 ## Base URL 40 41 The example request URLs shown in this document are for the public [Terraform 42 Registry](https://registry.terraform.io), and use its API `<base_url>` of 43 `https://registry.terraform.io/v1/modules/`. Note that although the base URL in 44 the [discovery document](#service-discovery) _may include_ a trailing slash, we 45 include a slash after the placeholder in the `Path`s below for clarity. 46 47 ## List Modules 48 49 These endpoints list modules according to some criteria. 50 51 | Method | Path | Produces | 52 | ------ | ------------------------------------- | -------------------------- | 53 | `GET` | `<base_url>` | `application/json` | 54 | `GET` | `<base_url>/:namespace` | `application/json` | 55 56 ### Parameters 57 58 - `namespace` `(string: <optional>)` - Restricts listing to modules published by 59 this user or organization. This is optionally specified as part of the URL 60 path. 61 62 ### Query Parameters 63 64 - `offset`, `limit` `(int: <optional>)` - See [Pagination](#pagination) for details. 65 - `provider` `(string: <optional>)` - Limits modules to a specific provider. 66 - `verified` `(bool: <optional>)` - If `true`, limits results to only verified 67 modules. Any other value including none returns all modules _including_ 68 verified ones. 69 70 ### Sample Request 71 72 ```text 73 $ curl 'https://registry.terraform.io/v1/modules?limit=2&verified=true' 74 ``` 75 76 ### Sample Response 77 78 ```json 79 { 80 "meta": { 81 "limit": 2, 82 "current_offset": 0, 83 "next_offset": 2, 84 "next_url": "/v1/modules?limit=2&offset=2&verified=true" 85 }, 86 "modules": [ 87 { 88 "id": "GoogleCloudPlatform/lb-http/google/1.0.4", 89 "owner": "", 90 "namespace": "GoogleCloudPlatform", 91 "name": "lb-http", 92 "version": "1.0.4", 93 "provider": "google", 94 "description": "Modular Global HTTP Load Balancer for GCE using forwarding rules.", 95 "source": "https://github.com/GoogleCloudPlatform/terraform-google-lb-http", 96 "published_at": "2017-10-17T01:22:17.792066Z", 97 "downloads": 213, 98 "verified": true 99 }, 100 { 101 "id": "terraform-aws-modules/vpc/aws/1.5.1", 102 "owner": "", 103 "namespace": "terraform-aws-modules", 104 "name": "vpc", 105 "version": "1.5.1", 106 "provider": "aws", 107 "description": "Terraform module which creates VPC resources on AWS", 108 "source": "https://github.com/terraform-aws-modules/terraform-aws-vpc", 109 "published_at": "2017-11-23T10:48:09.400166Z", 110 "downloads": 29714, 111 "verified": true 112 } 113 ] 114 } 115 ``` 116 117 ## Search Modules 118 119 This endpoint allows searching modules. 120 121 | Method | Path | Produces | 122 | ------ | ------------------------------------- | -------------------------- | 123 | `GET` | `<base_url>/search` | `application/json` | 124 125 ### Query Parameters 126 127 - `q` `(string: <required>)` - The search string. Search syntax understood 128 depends on registry implementation. The public registry supports basic keyword 129 or phrase searches. 130 - `offset`, `limit` `(int: <optional>)` - See [Pagination](#pagination) for details. 131 - `provider` `(string: <optional>)` - Limits results to a specific provider. 132 - `namespace` `(string: <optional>)` - Limits results to a specific namespace. 133 - `verified` `(bool: <optional>)` - If `true`, limits results to only verified 134 modules. Any other value including none returns all modules _including_ 135 verified ones. 136 137 ### Sample Request 138 139 ```text 140 $ curl 'https://registry.terraform.io/v1/modules/search?q=network&limit=2' 141 ``` 142 143 ### Sample Response 144 145 ```json 146 { 147 "meta": { 148 "limit": 2, 149 "current_offset": 0, 150 "next_offset": 2, 151 "next_url": "/v1/modules/search?limit=2&offset=2&q=network" 152 }, 153 "modules": [ 154 { 155 "id": "zoitech/network/aws/0.0.3", 156 "owner": "", 157 "namespace": "zoitech", 158 "name": "network", 159 "version": "0.0.3", 160 "provider": "aws", 161 "description": "This module is intended to be used for configuring an AWS network.", 162 "source": "https://github.com/zoitech/terraform-aws-network", 163 "published_at": "2017-11-23T15:12:06.620059Z", 164 "downloads": 39, 165 "verified": false 166 }, 167 { 168 "id": "Azure/network/azurerm/1.1.1", 169 "owner": "", 170 "namespace": "Azure", 171 "name": "network", 172 "version": "1.1.1", 173 "provider": "azurerm", 174 "description": "Terraform Azure RM Module for Network", 175 "source": "https://github.com/Azure/terraform-azurerm-network", 176 "published_at": "2017-11-22T17:15:34.325436Z", 177 "downloads": 1033, 178 "verified": true 179 } 180 ] 181 } 182 ``` 183 184 ## List Available Versions for a Specific Module 185 186 This is the primary endpoint for resolving module sources, returning the 187 available versions for a given fully-qualified module. 188 189 | Method | Path | Produces | 190 | ------ | ------------------------------------- | -------------------------- | 191 | `GET` | `<base_url>/:namespace/:name/:provider/versions` | `application/json` | 192 193 ### Parameters 194 195 - `namespace` `(string: <required>)` - The user or organization the module is 196 owned by. This is required and is specified as part of the URL path. 197 198 - `name` `(string: <required>)` - The name of the module. 199 This is required and is specified as part of the URL path. 200 201 - `provider` `(string: <required>)` - The name of the provider. 202 This is required and is specified as part of the URL path. 203 204 ### Sample Request 205 206 ```text 207 $ curl https://registry.terraform.io/v1/modules/hashicorp/consul/aws/versions 208 ``` 209 210 ### Sample Response 211 212 The `modules` array in the response always includes the requested module as the 213 first element. Other elements of this list, if present, are dependencies of the 214 requested module that are provided to potentially avoid additional requests to 215 resolve these modules. 216 217 Additional modules are not required to be provided but, when present, can be 218 used by Terraform to optimize the module installation process. 219 220 Each returned module has an array of available versions, which Terraform 221 matches against any version constraints given in configuration. 222 223 ```json 224 { 225 "modules": [ 226 { 227 "source": "hashicorp/consul/aws", 228 "versions": [ 229 { 230 "version": "0.0.1", 231 "submodules" : [ 232 { 233 "path": "modules/consul-cluster", 234 "providers": [ 235 { 236 "name": "aws", 237 "version": "" 238 } 239 ], 240 "dependencies": [] 241 }, 242 { 243 "path": "modules/consul-security-group-rules", 244 "providers": [ 245 { 246 "name": "aws", 247 "version": "" 248 } 249 ], 250 "dependencies": [] 251 }, 252 { 253 "providers": [ 254 { 255 "name": "aws", 256 "version": "" 257 } 258 ], 259 "dependencies": [], 260 "path": "modules/consul-iam-policies" 261 } 262 ], 263 "root": { 264 "dependencies": [], 265 "providers": [ 266 { 267 "name": "template", 268 "version": "" 269 }, 270 { 271 "name": "aws", 272 "version": "" 273 } 274 ] 275 } 276 } 277 ] 278 } 279 ] 280 } 281 ``` 282 283 ## Download Source Code for a Specific Module Version 284 285 This endpoint downloads the specified version of a module for a single provider. 286 287 A successful response has no body, and includes the location from which the module 288 version's source can be downloaded in the `X-Terraform-Get` header. Note that 289 this string may contain special syntax interpreted by Terraform via 290 [`go-getter`](https://github.com/hashicorp/go-getter). See the [`go-getter` 291 documentation](https://github.com/hashicorp/go-getter#url-format) for details. 292 293 The value of `X-Terraform-Get` may instead be a relative URL, indicated by 294 beginning with `/`, `./` or `../`, in which case it is resolved relative to 295 the full URL of the download endpoint. 296 297 | Method | Path | Produces | 298 | ------ | ---------------------------- | -------------------------- | 299 | `GET` | `<base_url>/:namespace/:name/:provider/:version/download` | `application/json` | 300 301 ### Parameters 302 303 - `namespace` `(string: <required>)` - The user the module is owned by. 304 This is required and is specified as part of the URL path. 305 306 - `name` `(string: <required>)` - The name of the module. 307 This is required and is specified as part of the URL path. 308 309 - `provider` `(string: <required>)` - The name of the provider. 310 This is required and is specified as part of the URL path. 311 312 - `version` `(string: <required>)` - The version of the module. 313 This is required and is specified as part of the URL path. 314 315 ### Sample Request 316 317 ```text 318 $ curl -i \ 319 https://registry.terraform.io/v1/modules/hashicorp/consul/aws/0.0.1/download 320 ``` 321 322 ### Sample Response 323 324 ```text 325 HTTP/1.1 204 No Content 326 Content-Length: 0 327 X-Terraform-Get: https://api.github.com/repos/hashicorp/terraform-aws-consul/tarball/v0.0.1//*?archive=tar.gz 328 ``` 329 330 ## List Latest Version of Module for All Providers 331 332 This endpoint returns the latest version of each provider for a module. 333 334 | Method | Path | Produces | 335 | ------ | ---------------------------- | -------------------------- | 336 | `GET` | `<base_url>/:namespace/:name` | `application/json` | 337 338 ### Parameters 339 340 - `namespace` `(string: <required>)` - The user or organization the module is 341 owned by. This is required and is specified as part of the URL path. 342 343 - `name` `(string: <required>)` - The name of the module. 344 This is required and is specified as part of the URL path. 345 346 ### Query Parameters 347 348 - `offset`, `limit` `(int: <optional>)` - See [Pagination](#pagination) for details. 349 350 ### Sample Request 351 352 ```text 353 $ curl \ 354 https://registry.terraform.io/v1/modules/hashicorp/consul 355 ``` 356 357 ### Sample Response 358 359 ```json 360 { 361 "meta": { 362 "limit": 15, 363 "current_offset": 0 364 }, 365 "modules": [ 366 { 367 "id": "hashicorp/consul/azurerm/0.0.1", 368 "owner": "gruntwork-team", 369 "namespace": "hashicorp", 370 "name": "consul", 371 "version": "0.0.1", 372 "provider": "azurerm", 373 "description": "A Terraform Module for how to run Consul on AzureRM using Terraform and Packer", 374 "source": "https://github.com/hashicorp/terraform-azurerm-consul", 375 "published_at": "2017-09-14T23:22:59.923047Z", 376 "downloads": 100, 377 "verified": false 378 }, 379 { 380 "id": "hashicorp/consul/aws/0.0.1", 381 "owner": "gruntwork-team", 382 "namespace": "hashicorp", 383 "name": "consul", 384 "version": "0.0.1", 385 "provider": "aws", 386 "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer", 387 "source": "https://github.com/hashicorp/terraform-aws-consul", 388 "published_at": "2017-09-14T23:22:44.793647Z", 389 "downloads": 113, 390 "verified": false 391 } 392 ] 393 } 394 ``` 395 396 ## Latest Version for a Specific Module Provider 397 398 This endpoint returns the latest version of a module for a single provider. 399 400 | Method | Path | Produces | 401 | ------ | ---------------------------- | -------------------------- | 402 | `GET` | `<base_url>/:namespace/:name/:provider` | `application/json` | 403 404 ### Parameters 405 406 - `namespace` `(string: <required>)` - The user the module is owned by. 407 This is required and is specified as part of the URL path. 408 409 - `name` `(string: <required>)` - The name of the module. 410 This is required and is specified as part of the URL path. 411 412 - `provider` `(string: <required>)` - The name of the provider. 413 This is required and is specified as part of the URL path. 414 415 ### Sample Request 416 417 ```text 418 $ curl \ 419 https://registry.terraform.io/v1/modules/hashicorp/consul/aws 420 ``` 421 422 ### Sample Response 423 424 Note this response has has some fields trimmed for clarity. 425 426 ```json 427 { 428 "id": "hashicorp/consul/aws/0.0.1", 429 "owner": "gruntwork-team", 430 "namespace": "hashicorp", 431 "name": "consul", 432 "version": "0.0.1", 433 "provider": "aws", 434 "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer", 435 "source": "https://github.com/hashicorp/terraform-aws-consul", 436 "published_at": "2017-09-14T23:22:44.793647Z", 437 "downloads": 113, 438 "verified": false, 439 "root": { 440 "path": "", 441 "readme": "# Consul AWS Module\n\nThis repo contains a Module for how to deploy a [Consul]...", 442 "empty": false, 443 "inputs": [ 444 { 445 "name": "ami_id", 446 "description": "The ID of the AMI to run in the cluster. ...", 447 "default": "\"\"" 448 }, 449 { 450 "name": "aws_region", 451 "description": "The AWS region to deploy into (e.g. us-east-1).", 452 "default": "\"us-east-1\"" 453 } 454 ], 455 "outputs": [ 456 { 457 "name": "num_servers", 458 "description": "" 459 }, 460 { 461 "name": "asg_name_servers", 462 "description": "" 463 } 464 ], 465 "dependencies": [], 466 "resources": [] 467 }, 468 "submodules": [ 469 { 470 "path": "modules/consul-cluster", 471 "readme": "# Consul Cluster\n\nThis folder contains a [Terraform](https://www.terraform.io/) ...", 472 "empty": false, 473 "inputs": [ 474 { 475 "name": "cluster_name", 476 "description": "The name of the Consul cluster (e.g. consul-stage). This variable is used to namespace all resources created by this module.", 477 "default": "" 478 }, 479 { 480 "name": "ami_id", 481 "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.", 482 "default": "" 483 } 484 ], 485 "outputs": [ 486 { 487 "name": "asg_name", 488 "description": "" 489 }, 490 { 491 "name": "cluster_size", 492 "description": "" 493 } 494 ], 495 "dependencies": [], 496 "resources": [ 497 { 498 "name": "autoscaling_group", 499 "type": "aws_autoscaling_group" 500 }, 501 { 502 "name": "launch_configuration", 503 "type": "aws_launch_configuration" 504 } 505 ] 506 } 507 ], 508 "providers": [ 509 "aws", 510 "azurerm" 511 ], 512 "versions": [ 513 "0.0.1" 514 ] 515 } 516 ``` 517 518 ## Get a Specific Module 519 520 This endpoint returns the specified version of a module for a single provider. 521 522 | Method | Path | Produces | 523 | ------ | ---------------------------- | -------------------------- | 524 | `GET` | `<base_url>/:namespace/:name/:provider/:version` | `application/json` | 525 526 ### Parameters 527 528 - `namespace` `(string: <required>)` - The user the module is owned by. 529 This is required and is specified as part of the URL path. 530 531 - `name` `(string: <required>)` - The name of the module. 532 This is required and is specified as part of the URL path. 533 534 - `provider` `(string: <required>)` - The name of the provider. 535 This is required and is specified as part of the URL path. 536 537 - `version` `(string: <required>)` - The version of the module. 538 This is required and is specified as part of the URL path. 539 540 ### Sample Request 541 542 ```text 543 $ curl \ 544 https://registry.terraform.io/v1/modules/hashicorp/consul/aws/0.0.1 545 ``` 546 547 ### Sample Response 548 549 Note this response has has some fields trimmed for clarity. 550 551 552 ```json 553 { 554 "id": "hashicorp/consul/aws/0.0.1", 555 "owner": "gruntwork-team", 556 "namespace": "hashicorp", 557 "name": "consul", 558 "version": "0.0.1", 559 "provider": "aws", 560 "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer", 561 "source": "https://github.com/hashicorp/terraform-aws-consul", 562 "published_at": "2017-09-14T23:22:44.793647Z", 563 "downloads": 113, 564 "verified": false, 565 "root": { 566 "path": "", 567 "readme": "# Consul AWS Module\n\nThis repo contains a Module for how to deploy a [Consul]...", 568 "empty": false, 569 "inputs": [ 570 { 571 "name": "ami_id", 572 "description": "The ID of the AMI to run in the cluster. ...", 573 "default": "\"\"" 574 }, 575 { 576 "name": "aws_region", 577 "description": "The AWS region to deploy into (e.g. us-east-1).", 578 "default": "\"us-east-1\"" 579 } 580 ], 581 "outputs": [ 582 { 583 "name": "num_servers", 584 "description": "" 585 }, 586 { 587 "name": "asg_name_servers", 588 "description": "" 589 } 590 ], 591 "dependencies": [], 592 "resources": [] 593 }, 594 "submodules": [ 595 { 596 "path": "modules/consul-cluster", 597 "readme": "# Consul Cluster\n\nThis folder contains a [Terraform](https://www.terraform.io/) ...", 598 "empty": false, 599 "inputs": [ 600 { 601 "name": "cluster_name", 602 "description": "The name of the Consul cluster (e.g. consul-stage). This variable is used to namespace all resources created by this module.", 603 "default": "" 604 }, 605 { 606 "name": "ami_id", 607 "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.", 608 "default": "" 609 } 610 ], 611 "outputs": [ 612 { 613 "name": "asg_name", 614 "description": "" 615 }, 616 { 617 "name": "cluster_size", 618 "description": "" 619 } 620 ], 621 "dependencies": [], 622 "resources": [ 623 { 624 "name": "autoscaling_group", 625 "type": "aws_autoscaling_group" 626 }, 627 { 628 "name": "launch_configuration", 629 "type": "aws_launch_configuration" 630 } 631 ] 632 } 633 ], 634 "providers": [ 635 "aws", 636 "azurerm" 637 ], 638 "versions": [ 639 "0.0.1" 640 ] 641 } 642 ``` 643 644 ## Download the Latest Version of a Module 645 646 This endpoint downloads the latest version of a module for a single provider. 647 648 It returns a 302 redirect whose `Location` header redirects the client to the 649 download endpoint (above) for the latest version. 650 651 | Method | Path | Produces | 652 | ------ | ---------------------------- | -------------------------- | 653 | `GET` | `<base_url>/:namespace/:name/:provider/download` | `application/json` | 654 655 ### Parameters 656 657 - `namespace` `(string: <required>)` - The user the module is owned by. 658 This is required and is specified as part of the URL path. 659 660 - `name` `(string: <required>)` - The name of the module. 661 This is required and is specified as part of the URL path. 662 663 - `provider` `(string: <required>)` - The name of the provider. 664 This is required and is specified as part of the URL path. 665 666 ### Sample Request 667 668 ```text 669 $ curl -i \ 670 https://registry.terraform.io/v1/modules/hashicorp/consul/aws/download 671 ``` 672 673 ### Sample Response 674 675 ```text 676 HTTP/1.1 302 Found 677 Location: /v1/modules/hashicorp/consul/aws/0.0.1/download 678 Content-Length: 70 679 Content-Type: text/html; charset=utf-8 680 681 <a href="/v1/modules/hashicorp/consul/aws/0.0.1/download">Found</a>. 682 ``` 683 684 ## HTTP Status Codes 685 686 The API follows regular HTTP status semantics. To make implementing a complete 687 client easier, some details on our policy and potential future status codes are 688 listed below. A robust client should consider how to handle all of the 689 following. 690 691 - **Success:** Return status is `200` on success with a body or `204` if there 692 is no body data to return. 693 - **Redirects:** Moved or aliased endpoints redirect with a `301`. Endpoints 694 redirecting to the latest version of a module may redirect with `302` or 695 `307` to indicate that they logically point to different resources over time. 696 - **Client Errors:** Invalid requests will receive the relevant `4xx` status. 697 Except where noted below, the request should not be retried. 698 - **Rate Limiting:** Clients placing excessive load on the service might be 699 rate-limited and receive a `429` code. This should be interpreted as a sign 700 to slow down, and wait some time before retrying the request. 701 - **Service Errors:** The usual `5xx` errors will be returned for service 702 failures. In all cases it is safe to retry the request after receiving a 703 `5xx` response. 704 - **Load Shedding:** A `503` response indicates that the service is under load 705 and can't process your request immediately. As with other `5xx` errors you 706 may retry after some delay, although clients should consider being more 707 lenient with retry schedule in this case. 708 709 ## Error Responses 710 711 When a `4xx` or `5xx` status code is returned. The response payload will look 712 like the following example: 713 714 ```json 715 { 716 "errors": [ 717 "something bad happened" 718 ] 719 } 720 ``` 721 722 The `errors` key is a list containing one or more strings where each string 723 describes an error that has occurred. 724 725 Note that it is possible that some `5xx` errors might result in a response that 726 is not in JSON format above due to being returned by an intermediate proxy. 727 728 ## Pagination 729 730 Endpoints that return lists of results use a common pagination format. 731 732 They accept positive integer query variables `offset` and `limit` which have the 733 usual SQL-like semantics. Each endpoint will have a sane default limit and a 734 default offset of `0`. Each endpoint will also apply a sane maximum limit, 735 requesting more results will just result in the maximum limit being used. 736 737 The response for a paginated result set will look like: 738 739 ```json 740 { 741 "meta": { 742 "limit": 15, 743 "current_offset": 15, 744 "next_offset": 30, 745 "prev_offset": 0, 746 }, 747 "<object name>": [] 748 } 749 ``` 750 Note that: 751 - `next_offset` will only be present if there are more results available. 752 - `prev_offset` will only be present if not at `offset = 0`. 753 - `limit` is the actual limit that was applied, it may be lower than the requested limit param. 754 - The key for the result array varies based on the endpoint and will be the 755 type of result pluralized, for example `modules`.