Class: GdsApi::PublishingApiV2

Inherits:
Base
  • Object
show all
Defined in:
lib/gds_api/publishing_api_v2.rb

Overview

Adapter for the Publishing API.

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

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

Discard a draft

Deletes the draft content item.

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:



176
177
178
179
180
181
182
183
184
185
# File 'lib/gds_api/publishing_api_v2.rb', line 176

def discard_draft(content_id, options = {})
  optional_keys = [
    :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.

Options Hash (params):

  • locale (String)

    The language, defaults to 'en' in publishing-api.

Raises:

See Also:



32
33
34
# File 'lib/gds_api/publishing_api_v2.rb', line 32

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

#get_content!Object



37
38
39
# File 'lib/gds_api/publishing_api_v2.rb', line 37

def get_content!(*)
  raise "`PublishingApiV2#get_content!` is deprecated. Use `PublishingApiV2#get_content`"
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'
)

See Also:



317
318
319
320
# File 'lib/gds_api/publishing_api_v2.rb', line 317

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.



330
331
332
333
334
335
336
337
338
339
340
341
342
# File 'lib/gds_api/publishing_api_v2.rb', line 330

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.



372
373
374
# File 'lib/gds_api/publishing_api_v2.rb', line 372

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

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)
      }
    ]
  }
}

See Also:



258
259
260
261
262
263
264
265
# File 'lib/gds_api/publishing_api_v2.rb', line 258

def get_expanded_links(content_id, with_drafts: true, generate: false)
  params = {}
  params[:with_drafts] = "false" unless with_drafts
  params[:generate] = "true" if generate
  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



347
348
349
350
351
352
353
# File 'lib/gds_api/publishing_api_v2.rb', line 347

def get_linkables(document_type: nil)
  if document_type.nil?
    raise ArgumentError.new("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



358
359
360
361
362
# File 'lib/gds_api/publishing_api_v2.rb', line 358

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 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
}

See Also:



208
209
210
# File 'lib/gds_api/publishing_api_v2.rb', line 208

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

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']
)


229
230
231
# File 'lib/gds_api/publishing_api_v2.rb', line 229

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

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 }
}


419
420
421
# File 'lib/gds_api/publishing_api_v2.rb', line 419

def get_links_for_content_ids(content_ids)
  post_json("#{endpoint}/v2/links/by-content-id", content_ids: content_ids).to_hash
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.



384
385
386
387
388
389
390
391
392
393
394
395
# File 'lib/gds_api/publishing_api_v2.rb', line 384

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

#import(content_id, locale, content_items) ⇒ Object

Import content into the publishing API

The publishing-api will delete any content which has the content id provided, and then import the data given.



126
127
128
129
130
131
132
# File 'lib/gds_api/publishing_api_v2.rb', line 126

def import(content_id, locale, content_items)
  params = {
    history: content_items,
  }

  post_json("#{endpoint}/v2/content/#{content_id}/import?locale=#{locale}", params)
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 #lookup_content_ids.

Examples:


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

See Also:



81
82
83
84
85
86
87
88
89
# File 'lib/gds_api/publishing_api_v2.rb', line 81

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_document_types,
    exclude_unpublishing_types: exclude_unpublishing_types,
    with_drafts: 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" }

See Also:



54
55
56
57
58
59
60
61
# File 'lib/gds_api/publishing_api_v2.rb', line 54

def lookup_content_ids(base_paths:, exclude_document_types: nil, exclude_unpublishing_types: nil, with_drafts: false)
  options = { base_paths: 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 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
)

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:



287
288
289
290
291
292
293
294
295
# File 'lib/gds_api/publishing_api_v2.rb', line 287

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

  payload = merge_optional_keys(payload, params, [: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.

Options Hash (options):

  • locale (String)

    The language, defaults to 'en' in publishing-api.

See Also:



102
103
104
105
106
107
108
109
110
111
112
113
114
115
# File 'lib/gds_api/publishing_api_v2.rb', line 102

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

  optional_keys = [
    :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



16
17
18
# File 'lib/gds_api/publishing_api_v2.rb', line 16

def put_content(content_id, payload)
  put_json(content_url(content_id), payload)
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.



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
# File 'lib/gds_api/publishing_api_v2.rb', line 150

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: 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