From 06f067b4e6e8710b75c6f5c5a7a14c6edcf93041 Mon Sep 17 00:00:00 2001 From: Paul Banks Date: Tue, 5 Dec 2017 19:38:16 +0000 Subject: [PATCH] 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 | 4 +- website/docs/registry/api.html.md | 159 ++++++++++++++++++++++++++++-- 2 files changed, 153 insertions(+), 10 deletions(-) diff --git a/config/module/module_test.go b/config/module/module_test.go index 9685f7feef..931f97bbbd 100644 --- a/config/module/module_test.go +++ b/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() diff --git a/website/docs/registry/api.html.md b/website/docs/registry/api.html.md index a0e85fc95d..d5f342b216 100644 --- a/website/docs/registry/api.html.md +++ b/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 -[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 `` 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` | `` | `application/json` | +| `GET` | `/:namespace` | `application/json` | + +### Parameters + +- `namespace` `(string: )` - 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: )` - See [Pagination](#Pagination) for details. +- `provider` `(string: )` - Limits modules to a specific provider. +- `verified` `(bool: )` - 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` | `/search` | `application/json` | + +### Query Parameters + +- `q` `(string: )` - The search string. Search syntax understood + depends on registry implementation. The public registry supports basic keyword + or phrase searches. +- `offset`, `limit` `(int: )` - See [Pagination](#Pagination) for details. +- `provider` `(string: )` - Limits results to a specific provider. +- `namespace` `(string: )` - Limits results to a specific namespace. +- `verified` `(bool: )` - 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` | `/: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` | `/: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` | `/: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` | `/: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` | `/: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` | `/:namespace/:name/:provider/download` | `application/json` | ### Parameters