Class: GdsApi::PublishingApi

Inherits:
Base
  • Object
show all
Defined in:
lib/gds_api/publishing_api.rb,
lib/gds_api/publishing_api/special_route_publisher.rb

Overview

Adapter for the Publishing API.

See Also:

Defined Under Namespace

Classes: NoLiveVersion, SpecialRoutePublisher

Instance Attribute Summary

Attributes inherited from Base

#options

Instance Method Summary collapse

Methods inherited from Base

#client, #create_client, #get_list, #initialize, #url_for_slug

Constructor Details

This class inherits a constructor from GdsApi::Base

Instance Method Details

#destroy_intent(base_path) ⇒ Object

Delete a publishing intent for a base_path.

Parameters:

  • base_path (String)

See Also:



500
501
502
503
504
 
# File 'lib/gds_api/publishing_api.rb', line 500

def destroy_intent(base_path)
  delete_json(intent_url(base_path))
rescue GdsApi::HTTPNotFound => e
  e
end

#discard_draft(content_id, options = {}) ⇒ Object

Discard a draft

Deletes the draft content item.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • locale (String) —

    The language, defaults to ‘en’ in publishing-api.

  • previous_version (Integer) —

    used to ensure the request is discarding the latest lock version of the draft

See Also:



195
196
197
198
199
200
201
 
# File 'lib/gds_api/publishing_api.rb', line 195

def discard_draft(content_id, options = {})
  optional_keys = %i[locale previous_version]

  params = merge_optional_keys({}, options, optional_keys)

  post_json(discard_url(content_id), params)
end

#get_content(content_id, params = {}) ⇒ GdsApi::Response

Return a content item

Raises exception if the item doesn’t exist.

Parameters:

  • content_id (UUID)
  • params (Hash) (defaults to: {})

Options Hash (params):

  • locale (String) —

    The language, defaults to ‘en’ in publishing-api.

Returns:

Raises:

See Also:



35
36
37
 
# File 'lib/gds_api/publishing_api.rb', line 35

def get_content(content_id, params = {})
  get_json(content_url(content_id, params))
end

#get_content_by_embedded_document(content_id) ⇒ GdsApi::Response

Get content items which embed a reusable content_id

No params are currently permitted.

The content items returned will be in either the draft of published state.

Examples:


publishing_api.get_content_by_embedded_document("4b148ebc-b2bb-40db-8e48-dd8cff363ff7")

Returns:

  • (GdsApi::Response) —

    A response containing a summarised list of the content items which embed the target.

See Also:



352
353
354
 
# File 'lib/gds_api/publishing_api.rb', line 352

def get_content_by_embedded_document(content_id)
  get_json("#{endpoint}/v2/content/#{content_id}/embedded")
end

#get_content_items(params) ⇒ Object

Get a list of content items from the Publishing API.

The only required key in the params hash is ‘document_type`. These will be used to filter down the content items being returned by the API. Other allowed options can be seen from the link below.

Examples:


publishing_api.get_content_items(
  document_type: 'taxon',
  q: 'Driving',
  page: 1,
  per_page: 50,
  publishing_app: 'content-tagger',
  fields: ['title', 'description', 'public_updated_at'],
  locale: 'en',
  order: '-public_updated_at'
)

Parameters:

  • params (Hash) —

    At minimum, this hash has to include the ‘document_type` of the content items we wish to see. All other optional keys are documented above.

See Also:



335
336
337
338
 
# File 'lib/gds_api/publishing_api.rb', line 335

def get_content_items(params)
  query = query_string(params)
  get_json("#{endpoint}/v2/content#{query}")
end

#get_content_items_enum(params) ⇒ Enumerator

Returns an Enumerator of content items for the provided query string parameters.

Parameters:

  • params (Hash)

Returns:

  • (Enumerator) —

    an enumerator of content items

See Also:



364
365
366
367
368
369
370
371
372
373
374
375
376
 
# File 'lib/gds_api/publishing_api.rb', line 364

def get_content_items_enum(params)
  Enumerator.new do |yielder|
    (1..Float::INFINITY).each do |index|
      merged_params = params.merge(page: index)
      page = get_content_items(merged_params).to_h
      results = page.fetch("results", [])
      results.each do |result|
        yielder << result
      end
      break if page.fetch("pages") <= index
    end
  end
end

#get_editions(params = {}) ⇒ GdsApi::Response

Returns a paginated list of editions for the provided query string parameters.

Parameters:

  • params (Hash) (defaults to: {})

Returns:

See Also:



406
407
408
 
# File 'lib/gds_api/publishing_api.rb', line 406

def get_editions(params = {})
  get_json(get_editions_url(params))
end

#get_expanded_links(content_id, locale: nil, with_drafts: true, generate: false) ⇒ Object

Get expanded links

Return the expanded links of the item.

Examples:


publishing_api.get_expanded_links("8157589b-65e2-4df6-92ba-2c91d80006c0", with_drafts: false).to_h

#=> {
  "generated" => "2017-08-01T10:42:49Z",
  "expanded_links" => {
    "organisations" => [
      {
        "content_id" => "21aa83a2-a47f-4189-a252-b02f8c322012",
        ... (and more attributes)
      }
    ]
  }
}

Parameters:

  • content_id (UUID)
  • locale (String) (defaults to: nil) —

    Locale with which to generate the expanded links. Unless this is specified, the default locale (‘en`) in the Publishing API will be used.

  • with_drafts (Bool) (defaults to: true) —

    Whether links to draft-only editions are returned, defaulting to ‘true`.

  • generate (Bool) (defaults to: false) —

    Whether to require publishing-api to generate the expanded links, which may be slow. Defaults to ‘false`.

See Also:



275
276
277
278
279
280
281
282
283
 
# File 'lib/gds_api/publishing_api.rb', line 275

def get_expanded_links(content_id, locale: nil, with_drafts: true, generate: false)
  params = {}
  params[:with_drafts] = "false" unless with_drafts
  params[:generate] = "true" if generate
  params[:locale] = locale if locale
  query = query_string(params)
  validate_content_id(content_id)
  get_json("#{endpoint}/v2/expanded-links/#{content_id}#{query}")
end

#get_linkables(document_type: nil) ⇒ Object

FIXME: Add documentation

See Also:



381
382
383
384
385
386
387
 
# File 'lib/gds_api/publishing_api.rb', line 381

def get_linkables(document_type: nil)
  if document_type.nil?
    raise ArgumentError, "Please provide a `document_type`"
  end

  get_json("#{endpoint}/v2/linkables?document_type=#{document_type}")
end

#get_linked_items(content_id, params = {}) ⇒ Object

FIXME: Add documentation

See Also:



392
393
394
395
396
 
# File 'lib/gds_api/publishing_api.rb', line 392

def get_linked_items(content_id, params = {})
  query = query_string(params)
  validate_content_id(content_id)
  get_json("#{endpoint}/v2/linked/#{content_id}#{query}")
end

#get_links(content_id) ⇒ GdsApi::Response

Get the link set for the given content_id.

Given a Content ID, it fetchs the existing link set and their version.

Examples:


publishing_api.get_links("a-content-id")
# => {
  "content_id" => "a-content-id",
  "links" => [
    "organisation" => "organisation-content-id",
    "document_collection" => "document-collection-content-id"
  ],
  "version" => 17
}

Parameters:

  • content_id (String)

Returns:

See Also:



224
225
226
 
# File 'lib/gds_api/publishing_api.rb', line 224

def get_links(content_id)
  get_json(links_url(content_id))
end

#get_links_changes(params) ⇒ Object

Returns an array of changes to links.

The link changes can be filtered by link_type, source content_id, target content_id and user. A maximum of 250 changes will be returned.

Examples:


publishing_api.get_links_changes(
  link_types: ['taxons'],
  target_content_ids: ['a544d48b-1e9e-47fb-b427-7a987c658c14']
)

Parameters:

  • link_types (Array) —

    Array of link_types to filter by.

  • source_content_ids (Array) —

    Array of source content ids to filter by.

  • target_content_ids (Array) —

    Array of target content ids to filter by.

  • users (Array) —

    User UIDs to filter by.



245
246
247
 
# File 'lib/gds_api/publishing_api.rb', line 245

def get_links_changes(params)
  get_json(links_changes_url(params))
end

#get_links_for_content_ids(content_ids) ⇒ Hash

Returns a mapping of content_ids => links hashes

Examples:


publishing_api.get_links_for_content_ids([
  "e1067450-7d13-45ff-ada4-5e3dd4025fb7",
  "72ed754c-4c82-415f-914a-ab6760454cb4"
])

#=> {
  "e1067450-7d13-45ff-ada4-5e3dd4025fb7" => {
    links: {
      taxons: ["13bba81c-b2b1-4b13-a3de-b24748977198"]},
      ... (and more attributes)
    version: 10},
  "72ed754c-4c82-415f-914a-ab6760454cb4" => { ..etc }
}

Parameters:

  • content_ids (Array)

Returns:

  • (Hash) —

    a mapping of content_id => links



453
454
455
 
# File 'lib/gds_api/publishing_api.rb', line 453

def get_links_for_content_ids(content_ids)
  post_json("#{endpoint}/v2/links/by-content-id", content_ids:).to_hash
end

#get_live_content(content_id, locale = "en") ⇒ GdsApi::Response

Return a live content item, i.e. content that has a state of “published” or “unpublished”

Raises exception if the item doesn’t exist.

Parameters:

  • content_id (UUID)
  • locale (Hash) (defaults to: "en") —

    a customizable set of options

Options Hash (locale):

  • locale (String) —

    The language, defaults to ‘en’ in publishing-api.

Returns:

Raises:

See Also:



50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/gds_api/publishing_api.rb', line 50

def get_live_content(content_id, locale = "en")
  content_item = get_content(content_id, locale:)

  live_states = %w[published unpublished]
  return content_item if live_states.include?(content_item.to_h["publication_state"])

  live_version_number = content_item["state_history"].find { |_, v| live_states.include?(v) }&.first
  raise NoLiveVersion, "No live version exists for content_id: #{content_id}" unless live_version_number

  get_content(content_id, locale:, version: live_version_number)
end

#get_paged_editions(params = {}) ⇒ Enumerator

Returns an Enumerator of Response objects for each page of results of editions for the provided query string parameters.

Parameters:

  • params (Hash) (defaults to: {})

Returns:

  • (Enumerator) —

    an enumerator of editions responses

See Also:



418
419
420
421
422
423
424
425
426
427
428
429
 
# File 'lib/gds_api/publishing_api.rb', line 418

def get_paged_editions(params = {})
  Enumerator.new do |yielder|
    next_link = get_editions_url(params)
    while next_link
      yielder.yield begin
        response = get_json(next_link)
      end
      next_link_info = response["links"].select { |link| link["rel"] == "next" }.first
      next_link = next_link_info && next_link_info["href"]
    end
  end
end

#get_schema(schema_name) ⇒ GdsApi::Response

Get a content schema by name

Examples:


publishing_api.get_schema("email_address")
  # => {
    "email_address" => {
        "type": "email_address",
        "required": ["email"],
        "properties": {
          "email": { "type" => "string" },
        },
      }
  }

Parameters:

  • schema_name (String)

Returns:

Raises:

See Also:



549
550
551
 
# File 'lib/gds_api/publishing_api.rb', line 549

def get_schema(schema_name)
  get_json("#{endpoint}/v2/schemas/#{schema_name}").to_hash
end

#get_schemas ⇒ GdsApi::Response

Get all schemas

Examples:


publishing_api.get_schemas()
  # => {
    "email_address" => {
        "type": "email_address",
        "required": ["email"],
        "properties": {
          "email": { "type" => "string" },
        },
      }
  }

Returns:

See Also:



524
525
526
 
# File 'lib/gds_api/publishing_api.rb', line 524

def get_schemas
  get_json("#{endpoint}/v2/schemas").to_hash
end

#lookup_content_id(base_path:, exclude_document_types: nil, exclude_unpublishing_types: nil, with_drafts: false) ⇒ UUID

Find the content_id for a base_path.

Convenience method if you only need to look up one content_id for a base_path. For multiple base_paths, use GdsApi::PublishingApiV2#lookup_content_ids.

Examples:


publishing_api.lookup_content_id(base_path: '/foo')
# => "51ac4247-fd92-470a-a207-6b852a97f2db"

Parameters:

  • base_path (String)
  • exclude_document_types (Array) (defaults to: nil) —

    (optional)

  • exclude_unpublishing_types (Array) (defaults to: nil) —

    (optional)

  • with_drafts (Boolean) (defaults to: false) —

    (optional)

Returns:

  • (UUID) —

    the ‘content_id` for the `base_path`

See Also:



102
103
104
105
106
107
108
109
110
 
# File 'lib/gds_api/publishing_api.rb', line 102

def lookup_content_id(base_path:, exclude_document_types: nil, exclude_unpublishing_types: nil, with_drafts: false)
  lookups = lookup_content_ids(
    base_paths: [base_path],
    exclude_document_types:,
    exclude_unpublishing_types:,
    with_drafts:,
  )
  lookups[base_path]
end

#lookup_content_ids(base_paths:, exclude_document_types: nil, exclude_unpublishing_types: nil, with_drafts: false) ⇒ Hash

Find the content_ids for a list of base_paths.

Examples:


publishing_api.lookup_content_ids(base_paths: ['/foo', '/bar'])
# => { "/foo" => "51ac4247-fd92-470a-a207-6b852a97f2db", "/bar" => "261bd281-f16c-48d5-82d2-9544019ad9ca" }

Parameters:

  • base_paths (Array)
  • exclude_document_types (Array) (defaults to: nil) —

    (optional)

  • exclude_unpublishing_types (Array) (defaults to: nil) —

    (optional)

  • with_drafts (Boolean) (defaults to: false) —

    (optional)

Returns:

  • (Hash) —

    a hash, keyed by ‘base_path` with `content_id` as value

See Also:



75
76
77
78
79
80
81
82
 
# File 'lib/gds_api/publishing_api.rb', line 75

def lookup_content_ids(base_paths:, exclude_document_types: nil, exclude_unpublishing_types: nil, with_drafts: false)
  options = { base_paths: }
  options[:exclude_document_types] = exclude_document_types if exclude_document_types
  options[:exclude_unpublishing_types] = exclude_unpublishing_types if exclude_unpublishing_types
  options[:with_drafts] = with_drafts if with_drafts
  response = post_json("#{endpoint}/lookup-by-base-path", options)
  response.to_hash
end

#patch_links(content_id, params) ⇒ Object

Patch the links of a content item

Examples:


publishing_api.patch_links(
  '86963c13-1f57-4005-b119-e7cf3cb92ecf',
  links: {
    topics: ['d6e1527d-d0c0-40d5-9603-b9f3e6866b8a'],
    mainstream_browse_pages: ['d6e1527d-d0c0-40d5-9603-b9f3e6866b8a'],
  },
  previous_version: 10,
  bulk_publishing: true
)

Parameters:

  • content_id (UUID)
  • params (Hash)

Options Hash (params):

  • links (Hash) —

    A “links hash”

  • previous_version (Integer) —

    The previous version (returned by ‘get_links`). If this version is not the current version, the publishing-api will reject the change and return 409 Conflict. (optional)

  • bulk_publishing (Boolean) —

    Set to true to indicate that this is part of a mass-republish. Allows the publishing-api to prioritise human-initiated publishing (optional, default false)

See Also:



305
306
307
308
309
310
311
312
313
 
# File 'lib/gds_api/publishing_api.rb', line 305

def patch_links(content_id, params)
  payload = {
    links: params.fetch(:links),
  }

  payload = merge_optional_keys(payload, params, %i[previous_version bulk_publishing])

  patch_json(links_url(content_id), payload)
end

#publish(content_id, update_type = nil, options = {}) ⇒ Object

Publish a content item

The publishing-api will “publish” a draft item, so that it will be visible on the public site.

Parameters:

  • content_id (UUID)
  • update_type (String) (defaults to: nil) —

    Either ‘major’, ‘minor’ or ‘republish’

  • options (Hash) (defaults to: {})

Options Hash (options):

  • locale (String) —

    The language, defaults to ‘en’ in publishing-api.

See Also:



123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/gds_api/publishing_api.rb', line 123

def publish(content_id, update_type = nil, options = {})
  params = {
    update_type:,
  }

  optional_keys = %i[locale previous_version]

  params = merge_optional_keys(params, options, optional_keys)

  post_json(publish_url(content_id), params)
end

#put_content(content_id, payload) ⇒ Object

Put a content item

Parameters:

  • content_id (UUID)
  • payload (Hash) —

    A valid content item

See Also:



19
20
21
 
# File 'lib/gds_api/publishing_api.rb', line 19

def put_content(content_id, payload)
  put_json(content_url(content_id), payload)
end

#put_intent(base_path, payload) ⇒ Object

Create a publishing intent for a base_path.

publishing_api.put_intent(

'/some/base_path',
{
  publish_time: '2024-03-15T09:00:00.000+00:00',
  publishing_app: 'content-publisher',
  rendering_app: 'government-frontend',
}

)

Parameters:

  • base_path (String)
  • payload (Hash)

See Also:



491
492
493
 
# File 'lib/gds_api/publishing_api.rb', line 491

def put_intent(base_path, payload)
  put_json(intent_url(base_path), payload)
end

#put_path(base_path, payload) ⇒ Object

Reserves a path for a publishing application

Returns success or failure only.

Parameters:

  • payload (Hash)

Options Hash (payload):

  • publishing_app (Hash) —

    The publishing application, like ‘content-tagger`

See Also:



465
466
467
468
 
# File 'lib/gds_api/publishing_api.rb', line 465

def put_path(base_path, payload)
  url = "#{endpoint}/paths#{base_path}"
  put_json(url, payload)
end

#republish(content_id, options = {}) ⇒ Object

Republish a content item

The publishing-api will “republish” a live edition. This can be used to remove an unpublishing or to re-send a published edition downstream

Parameters:

  • content_id (UUID)
  • options (Hash) (defaults to: {})

Options Hash (options):

  • locale (String) —

    The language, defaults to ‘en’ in publishing-api.

See Also:

  • ...


145
146
147
148
149
150
151
 
# File 'lib/gds_api/publishing_api.rb', line 145

def republish(content_id, options = {})
  optional_keys = %i[locale previous_version]

  params = merge_optional_keys({}, options, optional_keys)

  post_json(republish_url(content_id), params)
end

#unpublish(content_id, type:, explanation: nil, alternative_path: nil, discard_drafts: false, allow_draft: false, previous_version: nil, locale: nil, unpublished_at: nil, redirects: nil) ⇒ Object

Unpublish a content item

The publishing API will “unpublish” a live item, to remove it from the public site, or update an existing unpublishing.

Parameters:

  • content_id (UUID)
  • type (String) —

    Either ‘withdrawal’, ‘gone’ or ‘redirect’.

  • explanation (String) (defaults to: nil) —

    (optional) Text to show on the page.

  • alternative_path (String) (defaults to: nil) —

    (optional) Alternative path to show on the page or redirect to.

  • discard_drafts (Boolean) (defaults to: false) —

    (optional) Whether to discard drafts on that item. Defaults to false.

  • previous_version (Integer) (defaults to: nil) —

    (optional) A lock version number for optimistic locking.

  • locale (String) (defaults to: nil) —

    (optional) The content item locale.

  • unpublished_at (Time) (defaults to: nil) —

    (optional) The time the content was withdrawn. Ignored for types other than withdrawn

  • redirects (Array) (defaults to: nil) —

    (optional) Required if no alternative_path is given. An array of redirect values, ie: { path:, type:, destination: }

See Also:



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/gds_api/publishing_api.rb', line 169

def unpublish(content_id, type:, explanation: nil, alternative_path: nil, discard_drafts: false, allow_draft: false, previous_version: nil, locale: nil, unpublished_at: nil, redirects: nil)
  params = {
    type:,
  }

  params[:explanation] = explanation if explanation
  params[:alternative_path] = alternative_path if alternative_path
  params[:previous_version] = previous_version if previous_version
  params[:discard_drafts] = discard_drafts if discard_drafts
  params[:allow_draft] = allow_draft if allow_draft
  params[:locale] = locale if locale
  params[:unpublished_at] = unpublished_at.utc.iso8601 if unpublished_at
  params[:redirects] = redirects if redirects

  post_json(unpublish_url(content_id), params)
end

#unreserve_path(base_path, publishing_app) ⇒ Object 



470
471
472
473
 
# File 'lib/gds_api/publishing_api.rb', line 470

def unreserve_path(base_path, publishing_app)
  payload = { publishing_app: }
  delete_json(unreserve_url(base_path), payload)
end