Add new section describing how to find module deprecation data using …

…the API (#811)
hashicorp · Jan 16, 2025 · 924abc6 · 924abc6
1 parent c3ec0aa
commit 924abc6
Showing 1 changed file with 85 additions and 6 deletions.
diff --git a/website/docs/cloud-docs/api-docs/private-registry/manage-module-versions.mdx b/website/docs/cloud-docs/api-docs/private-registry/manage-module-versions.mdx
@@ -77,7 +77,7 @@ This endpoint allows you to deprecate a specific module version. Deprecating a m
 | [422](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) | [JSON API error object](http://jsonapi.org/format/#error-objects) | Malformed request body, for example the request is missing attributes or uses the wrong types. |
 | [500](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) or [503](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) | [JSON API error object](http://jsonapi.org/format/#error-objects) | Failure occurred while deprecating a module version. |
 
-### **Sample Payload**
+### Sample payload
 
 ```json
 {
@@ -94,7 +94,7 @@ This endpoint allows you to deprecate a specific module version. Deprecating a m
 }
 ```
 
-### **Sample Request**
+### Sample request
 
 ```shell
 curl \
@@ -105,7 +105,7 @@ curl \
 https://app.terraform.io/api/v2/organizations/hashicorp/registry-modules/private/hashicorp/lb-http/google/11.0.0
 ```
 
-### Sample Response
+### Sample response
 
 ```json
 {
@@ -157,7 +157,7 @@ Deprecating a module version adds warnings to the run output of any consumers us
 | [422](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) | [JSON API error object](http://jsonapi.org/format/#error-objects) | Malformed request body, for example the request is missing attributes or uses the wrong types. |
 | [500](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) or [503] | [JSON API error object](http://jsonapi.org/format/#error-objects) | Failure occurred while reverting the deprecation of a module version. |
 
-### **Sample Request**
+### Sample request
 
 ```shell
 curl \
@@ -168,7 +168,7 @@ curl \
 https://app.terraform.io/api/v2/organizations/hashicorp/registry-modules/private/hashicorp/lb-http/google/11.0.0
 ```
 
-**Sample payload**
+### Sample payload
 
 ```json
 {
@@ -183,7 +183,7 @@ https://app.terraform.io/api/v2/organizations/hashicorp/registry-modules/private
 }
 ```
 
-### Sample Response
+### Sample response
 
 ```json
 {
@@ -193,3 +193,82 @@ https://app.terraform.io/api/v2/organizations/hashicorp/registry-modules/private
   }
 }
 ```
+
+## Fetch a module version’s deprecation data
+
+Send a `GET` request to the `/modules/:GitHub-organization/:module/:provider/versions` endpoint to retrieve data about private registry modules, including the module's deprecation status. Refer to the [private registry module API example](/terraform/cloud-docs/api-docs/private-registry/modules#sample-registry-request-private-module) for additional information.
+
+For example, if you want to know the deprecation status of v0.0.1 of the `aws` provider’s `consul` module in your `my-cloud-org` organization, you could perform the following API call:
+
+```shell
+curl \
+  --header "Authorization: Bearer $TOKEN" \
+  https://app.terraform.io/api/registry/v1/modules/my-cloud-org/consul/aws/0.0.1
+```
+
+If the module is deprecated, your response includes a `deprecation` key with the details of that module version’s deprecation.
+
+```json
+{
+  "id": "hashicorp/consul/aws/0.0.1",
+  "owner": "gruntwork-team",
+  "namespace": "hashicorp",
+  "name": "consul",
+  "version": "0.0.1",
+  "provider": "aws",
+  "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer"
+  // ... //
+  "deprecation": {
+    "reason": "This version was deprecated due to a vulnerability issue. Please upgrade to 0.0.2.",
+    "link": "https://hashicorp.com"
+  }
+}
+```
+
+To check the deprecation status of all of the `consul` module’s versions, you could perform the following API call:
+
+```shell
+curl \
+  --header "Authorization: Bearer $TOKEN" \
+  https://app.terraform.io/api/registry/v1/modules/my-cloud-org/consul/aws/versions
+```
+
+The response includes multiple versions, and each version has a `deprecation` key listing the details of that module’s deprecation. If a module version has not been deprecated, the `deprecation` field returns `null`.
+
+```json
+{
+  "modules": [
+    {
+      "source": "hashicorp/consul/aws",
+      "versions": [
+          {
+            "version": "0.0.1",
+            // ... //
+            "deprecation": {
+              "reason": "security vulnerability",
+              "link": "www.hashicorp.com"
+            }
+          },
+          {
+            "version": "0.0.2",
+            "submodules": [],
+            "root": {
+                "dependencies": [],
+                "providers": [
+                  {
+                      "name": "template",
+                      "version": ""
+                  },
+                  {
+                      "name": "aws",
+                      "version": ""
+                  }
+                ]
+            },
+            "deprecation": null
+        }
+      ]
+    }
+  ]
+}
+```