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

config/module/module_test.go

@@ -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()
 

website/docs/registry/api.html.md

@@ -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
+## Base URL
-[Terraform Registry](https://registry.terraform.io), and use its API base
+
-URL of `https://registry.terraform.io/v1/modules/` .
+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