Update registry API docs with browse and search (#16846)
* Verify discovery works without trailing slash on discovery URL * Update registry API docs with browse and search endpoints * Add sample request/responses * Add comment to test to indicate expecations * Fix typo * Remove trailing slash weirdness
This commit is contained in:
parent
703673fb9e
commit
06f067b4e6
|
@ -54,7 +54,9 @@ func testStorage(t *testing.T, d *disco.Disco) *Storage {
|
|||
// and example.com to the test server.
|
||||
func testDisco(s *httptest.Server) *disco.Disco {
|
||||
services := map[string]interface{}{
|
||||
"modules.v1": fmt.Sprintf("%s/v1/modules/", s.URL),
|
||||
// Note that both with and without trailing slashes are supported behaviours
|
||||
// TODO: add specific tests to enumerate both possibilities.
|
||||
"modules.v1": fmt.Sprintf("%s/v1/modules", s.URL),
|
||||
}
|
||||
d := disco.NewDisco()
|
||||
|
||||
|
|
|
@ -36,9 +36,150 @@ 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`.
|
||||
|
||||
The example request URLs shown in this document are for the public
|
||||
[Terraform Registry](https://registry.terraform.io), and use its API base
|
||||
URL of `https://registry.terraform.io/v1/modules/` .
|
||||
## Base URL
|
||||
|
||||
The example request URLs shown in this document are for the public [Terraform
|
||||
Registry](https://registry.terraform.io), and use its API `<base_url>` of
|
||||
`https://registry.terraform.io/v1/modules/`. Note that although the base URL in
|
||||
the [discovery document](#service-discovery) _may include_ a trailing slash, we
|
||||
include a slash after the placeholder in the `Path`s below for clarity.
|
||||
|
||||
## List Modules
|
||||
|
||||
These endpoints list modules according to some criteria.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------------------------- | -------------------------- |
|
||||
| `GET` | `<base_url>` | `application/json` |
|
||||
| `GET` | `<base_url>/:namespace` | `application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `namespace` `(string: <optional>)` - Restricts listing to modules published by
|
||||
this user or organization. This is optionally specified as part of the URL
|
||||
path.
|
||||
|
||||
### Query Parameters
|
||||
|
||||
- `offset`, `limit` `(int: <optional>)` - See [Pagination](#Pagination) for details.
|
||||
- `provider` `(string: <optional>)` - Limits modules to a specific provider.
|
||||
- `verified` `(bool: <optional>)` - If `true`, limits results to only verified
|
||||
modules. Any other value including none returns all modules _including_
|
||||
verified ones.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl 'https://registry.terraform.io/v1/modules&limit=2&verified=true'
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Search Modules
|
||||
|
||||
This endpoint allows searching modules.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------------------------- | -------------------------- |
|
||||
| `GET` | `<base_url>/search` | `application/json` |
|
||||
|
||||
### Query Parameters
|
||||
|
||||
- `q` `(string: <required>)` - The search string. Search syntax understood
|
||||
depends on registry implementation. The public registry supports basic keyword
|
||||
or phrase searches.
|
||||
- `offset`, `limit` `(int: <optional>)` - See [Pagination](#Pagination) for details.
|
||||
- `provider` `(string: <optional>)` - Limits results to a specific provider.
|
||||
- `namespace` `(string: <optional>)` - Limits results to a specific namespace.
|
||||
- `verified` `(bool: <optional>)` - If `true`, limits results to only verified
|
||||
modules. Any other value including none returns all modules _including_
|
||||
verified ones.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl 'https://registry.terraform.io/v1/modules/search?q=network&limit=2'
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## List Available Versions for a Specific Module
|
||||
|
||||
|
@ -47,7 +188,7 @@ available versions for a given fully-qualified module.
|
|||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------------------------- | -------------------------- |
|
||||
| `GET` | `:namespace/:name/:provider/versions` | `application/json` |
|
||||
| `GET` | `<base_url>/:namespace/:name/:provider/versions` | `application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
|
@ -155,7 +296,7 @@ the full URL of the download endpoint.
|
|||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `:namespace/:name/:provider/:version/download` | `application/json` |
|
||||
| `GET` | `<base_url>/:namespace/:name/:provider/:version/download` | `application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
|
@ -192,7 +333,7 @@ This endpoint returns the latest version of each provider for a module.
|
|||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `:namespace/:name` | `application/json` |
|
||||
| `GET` | `<base_url>/:namespace/:name` | `application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
|
@ -258,7 +399,7 @@ This endpoint returns the latest version of a module for a single provider.
|
|||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `:namespace/:name/:provider` | `application/json` |
|
||||
| `GET` | `<base_url>/:namespace/:name/:provider` | `application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
|
@ -380,7 +521,7 @@ This endpoint returns the specified version of a module for a single provider.
|
|||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `:namespace/:name/:provider/:version` | `application/json` |
|
||||
| `GET` | `<base_url>/:namespace/:name/:provider/:version` | `application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
|
@ -509,7 +650,7 @@ download endpoint (above) for the latest version.
|
|||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `:namespace/:name/:provider/download` | `application/json` |
|
||||
| `GET` | `<base_url>/:namespace/:name/:provider/download` | `application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
|
|
Loading…
Reference in New Issue