Rename embedded endpoint and associated method

We’ve renamed the endpoint to get host content for a content ID to
better reflect what it does. This updates the method to call the new
endpoint (we will soon retire the old one). To ensure backward
compatility, we alias the method too.

lib/gds_api/publishing_api.rb

@@ -342,18 +342,23 @@ def get_content_items(params)
   # @param content_id [UUID]
   # @param params [Hash]
   #
-  #   publishing_api.get_content_by_embedded_document(
+  #   publishing_api.get_host_content_for_content_id(
   #     "4b148ebc-b2bb-40db-8e48-dd8cff363ff7",
   #     { page: 1, order: '-last_edited_at' }
   #   )
   #
   # @return [GdsApi::Response] A response containing a summarised list of the content items which embed the target.
   # The content items returned will be in either the draft of published state.
   #
-  # @see https://github.com/alphagov/publishing-api/blob/main/docs/api.md#get-v2contentcontent_idembedded
-  def get_content_by_embedded_document(content_id, params = {})
+  # @see https://github.com/alphagov/publishing-api/blob/main/docs/api.md#get-v2contentcontent_idhost-content
+  def get_host_content_for_content_id(content_id, params = {})
     query = query_string(params)
-    get_json("#{endpoint}/v2/content/#{content_id}/embedded#{query}")
+    get_json("#{endpoint}/v2/content/#{content_id}/host-content#{query}")
+  end
+
+  def get_content_by_embedded_document(content_id, params = {})
+    warn "GdsAPI::PublishingApi: #get_content_by_embedded_document deprecated (please use #get_host_content_for_content_id)"
+    get_host_content_for_content_id(content_id, params)
   end
 
   # Returns an Enumerator of content items for the provided

test/pacts/publishing_api/get_embedded_content_pact_test.rb

@@ -1,7 +1,7 @@
 require "test_helper"
 require "gds_api/publishing_api"
 
-describe "GdsApi::PublishingApi#get_content_by_embedded_document pact tests" do
+describe "GdsApi::PublishingApi#get_host_content_for_content_id pact tests" do
   include PactTest
 
   let(:api_client) { GdsApi::PublishingApi.new(publishing_api_host) }
@@ -33,17 +33,17 @@
   it "responds with 200 if the target content item exists" do
     publishing_api
       .given("a content item exists (content_id: #{content_id}) that embeds the reusable content (content_id: #{reusable_content_id})")
-      .upon_receiving("a get_content_by_embedded_document request")
+      .upon_receiving("a get_host_content_for_content_id request")
       .with(
         method: :get,
-        path: "/v2/content/#{reusable_content_id}/embedded",
+        path: "/v2/content/#{reusable_content_id}/host-content",
       )
       .will_respond_with(
         status: 200,
         body: expected_body,
       )
 
-    response = api_client.get_content_by_embedded_document(reusable_content_id)
+    response = api_client.get_host_content_for_content_id(reusable_content_id)
 
     assert_equal(expected_body, response.parsed_content)
   end
@@ -69,10 +69,10 @@
 
     it "returns the first page of results" do
       publishing_api_with_multiple_content_items
-        .upon_receiving("a get_content_by_embedded_document request for multiple pages")
+        .upon_receiving("a get_host_content_for_content_id request for multiple pages")
         .with(
           method: :get,
-          path: "/v2/content/#{reusable_content_id}/embedded",
+          path: "/v2/content/#{reusable_content_id}/host-content",
         )
         .will_respond_with(
           status: 200,
@@ -84,15 +84,15 @@
           },
         )
 
-      api_client.get_content_by_embedded_document(reusable_content_id)
+      api_client.get_host_content_for_content_id(reusable_content_id)
     end
 
     it "supports a page argument" do
       publishing_api_with_multiple_content_items
-        .upon_receiving("a get_content_by_embedded_document request for multiple pages with a page argument")
+        .upon_receiving("a get_host_content_for_content_id request for multiple pages with a page argument")
         .with(
           method: :get,
-          path: "/v2/content/#{reusable_content_id}/embedded",
+          path: "/v2/content/#{reusable_content_id}/host-content",
           query: "page=2",
         )
         .will_respond_with(
@@ -105,15 +105,15 @@
           },
         )
 
-      api_client.get_content_by_embedded_document(reusable_content_id, { page: 2 })
+      api_client.get_host_content_for_content_id(reusable_content_id, { page: 2 })
     end
 
     it "supports a per page argument" do
       publishing_api_with_multiple_content_items
-        .upon_receiving("a get_content_by_embedded_document request for multiple pages with a per_page argument")
+        .upon_receiving("a get_host_content_for_content_id request for multiple pages with a per_page argument")
         .with(
           method: :get,
-          path: "/v2/content/#{reusable_content_id}/embedded",
+          path: "/v2/content/#{reusable_content_id}/host-content",
           query: "per_page=1",
         )
         .will_respond_with(
@@ -126,15 +126,15 @@
           },
         )
 
-      api_client.get_content_by_embedded_document(reusable_content_id, { per_page: 1 })
+      api_client.get_host_content_for_content_id(reusable_content_id, { per_page: 1 })
     end
 
     it "supports sorting" do
       publishing_api_with_multiple_content_items
-        .upon_receiving("a get_content_by_embedded_document request for multiple pages with sorting")
+        .upon_receiving("a get_host_content_for_content_id request for multiple pages with sorting")
         .with(
           method: :get,
-          path: "/v2/content/#{reusable_content_id}/embedded",
+          path: "/v2/content/#{reusable_content_id}/host-content",
           query: "order=-last_edited_at",
         )
         .will_respond_with(
@@ -147,25 +147,25 @@
           },
         )
 
-      api_client.get_content_by_embedded_document(reusable_content_id, { order: "-last_edited_at" })
+      api_client.get_host_content_for_content_id(reusable_content_id, { order: "-last_edited_at" })
     end
   end
 
   it "responds with 404 if the content item does not exist" do
     missing_content_id = "missing-content-id"
     publishing_api
       .given("no content exists")
-      .upon_receiving("a get_content_by_embedded_document request")
+      .upon_receiving("a get_host_content_for_content_id request")
       .with(
         method: :get,
-        path: "/v2/content/#{missing_content_id}/embedded",
+        path: "/v2/content/#{missing_content_id}/host-content",
       )
       .will_respond_with(
         status: 404,
       )
 
     assert_raises(GdsApi::HTTPNotFound) do
-      api_client.get_content_by_embedded_document(missing_content_id)
+      api_client.get_host_content_for_content_id(missing_content_id)
     end
   end
 end

test/publishing_api_test.rb

@@ -31,4 +31,15 @@
       end
     end
   end
+
+  describe "#get_content_by_embedded_document" do
+    it "sends a warning and calls #get_host_content_for_content_id" do
+      content_id = SecureRandom.uuid
+      args = { some: "args" }
+      api_client.expects(:warn).with("GdsAPI::PublishingApi: #get_content_by_embedded_document deprecated (please use #get_host_content_for_content_id)")
+      api_client.expects(:get_host_content_for_content_id).with(content_id, args)
+
+      api_client.get_content_by_embedded_document(content_id, args)
+    end
+  end
 end