class GdsApi::PublishingApiV2
@api documented
@see github.com/alphagov/publishing-api/blob/master/doc/model.md<br>@see github.com/alphagov/publishing-api/blob/master/doc/publishing-application-examples.md<br>@see github.com/alphagov/publishing-api<br><br>Adapter for the Publishing API.
def content_url(content_id, params = {})
def content_url(content_id, params = {}) validate_content_id(content_id) query = query_string(params) "#{endpoint}/v2/content/#{content_id}#{query}" end
def discard_draft(content_id, options = {})
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#post-v2contentcontent_iddiscard-draft -
Options Hash:
(**options)
-
previous_version
(Integer
) -- used to ensure the request is discarding the latest lock version of the draft -
locale
(String
) -- The language, defaults to 'en' in publishing-api.
Parameters:
-
options
(Hash
) --
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
def discard_url(content_id)
def discard_url(content_id) validate_content_id(content_id) "#{endpoint}/v2/content/#{content_id}/discard-draft" end
def get_content(content_id, params = {})
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#get-v2contentcontent_id -
Raises:
-
(HTTPNotFound)
- when the content item is not found
Returns:
-
(GdsApi::Response)
- a content item
Options Hash:
(**params)
-
locale
(String
) -- The language, defaults to 'en' in publishing-api.
Parameters:
-
params
(Hash
) -- -
content_id
(UUID
) --
def get_content(content_id, params = {}) get_json(content_url(content_id, params)) end
def get_content!(*)
- Private: -
def get_content!(*) raise "`PublishingApiV2#get_content!` is deprecated. Use `PublishingApiV2#get_content`" end
def get_content_items(params)
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#get-v2content -
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.
def get_content_items(params) query = query_string(params) get_json("#{endpoint}/v2/content#{query}") end
def get_editions(params = {})
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#get-v2editions -
Returns:
-
(GdsApi::Response)
- a paginated list of editions
Parameters:
-
params
(Hash
) --
def get_editions(params = {}) get_json(get_editions_url(params)) end
def get_editions_url(params)
def get_editions_url(params) query = query_string(params) "#{endpoint}/v2/editions#{query}" end
def get_expanded_links(content_id, with_drafts: true, generate: false)
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#get-v2expanded-linkscontent_id -
Parameters:
-
generate
(Bool
) -- Whether to require publishing-api to generate the expanded links, which may be slow. Defaults to `false`. -
with_drafts
(Bool
) -- Whether links to draft-only editions are returned, defaulting to `true`. -
content_id
(UUID
) --
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
def get_linkables(document_type: nil)
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#get-v2linkables -
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
def get_linked_items(content_id, params = {})
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#get-v2linkedcontent_id -
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
def get_links(content_id)
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#get-v2linkscontent_id -
Returns:
-
(GdsApi::Response)
- A response containing `links` and `version`.
Parameters:
-
content_id
(String
) --
def get_links(content_id) get_json(links_url(content_id)) end
def get_links_changes(params)
-
users
(Array
) -- User UIDs to filter by. -
target_content_ids
(Array
) -- Array of target content ids to filter by. -
source_content_ids
(Array
) -- Array of source content ids to filter by. -
link_types
(Array
) -- Array of link_types to filter by.
def get_links_changes(params) get_json(links_changes_url(params)) end
def get_links_for_content_ids(content_ids)
-
(Hash)
- a mapping of content_id => links
Parameters:
-
content_ids
(Array
) --
def get_links_for_content_ids(content_ids) post_json("#{endpoint}/v2/links/by-content-id", content_ids: content_ids).to_hash end
def get_paged_editions(params = {})
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#get-v2editions -
Returns:
-
(Enumerator)
- an enumerator of editions responses
Parameters:
-
params
(Hash
) --
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
def import(content_id, locale, content_items)
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#post-v2contentcontent_idimport -
Parameters:
-
content_items
(Array
) -- -
content_id
(UUID
) --
def import(content_id, locale, content_items) params = { history: content_items, } post_json("#{endpoint}/v2/content/#{content_id}/import?locale=#{locale}", params) end
def links_changes_url(params = {})
def links_changes_url(params = {}) query = query_string(params) "#{endpoint}/v2/links/changes#{query}" end
def links_url(content_id)
def links_url(content_id) validate_content_id(content_id) "#{endpoint}/v2/links/#{content_id}" end
def lookup_content_id(base_path:, exclude_document_types: nil, exclude_unpublishing_types: nil)
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#post-lookup-by-base-path -
Returns:
-
(UUID)
- the `content_id` for the `base_path`
Parameters:
-
exclude_unpublishing_types
(Array
) -- (optional) -
exclude_document_types
(Array
) -- (optional) -
base_path
(String
) --
def lookup_content_id(base_path:, exclude_document_types: nil, exclude_unpublishing_types: nil) lookups = lookup_content_ids( base_paths: [base_path], exclude_document_types: exclude_document_types, exclude_unpublishing_types: exclude_unpublishing_types ) lookups[base_path] end
def lookup_content_ids(base_paths:, exclude_document_types: nil, exclude_unpublishing_types: nil)
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#post-lookup-by-base-path -
Returns:
-
(Hash)
- a hash, keyed by `base_path` with `content_id` as value
Parameters:
-
exclude_unpublishing_types
(Array
) -- (optional) -
exclude_document_types
(Array
) -- (optional) -
base_paths
(Array
) --
def lookup_content_ids(base_paths:, exclude_document_types: nil, exclude_unpublishing_types: nil) 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 response = post_json("#{endpoint}/lookup-by-base-path", options) response.to_hash end
def merge_optional_keys(params, options, optional_keys)
def merge_optional_keys(params, options, optional_keys) optional_keys.each_with_object(params) do |optional_key, hash| hash.merge!(optional_key => options[optional_key]) if options[optional_key] end end
def patch_links(content_id, params)
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#patch-v2linkscontent_id -
Options Hash:
(**params)
-
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) -
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) -
links
(Hash
) -- A "links hash"
Parameters:
-
params
(Hash
) -- -
content_id
(UUID
) --
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
def publish(content_id, update_type = nil, options = {})
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#post-v2contentcontent_idpublish -
Options Hash:
(**options)
-
locale
(String
) -- The language, defaults to 'en' in publishing-api.
Parameters:
-
options
(Hash
) -- -
update_type
(String
) -- Either 'major', 'minor' or 'republish' -
content_id
(UUID
) --
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
def publish_url(content_id)
def publish_url(content_id) validate_content_id(content_id) "#{endpoint}/v2/content/#{content_id}/publish" end
def put_content(content_id, payload)
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#put-v2contentcontent_id -
Parameters:
-
payload
(Hash
) -- A valid content item -
content_id
(UUID
) --
def put_content(content_id, payload) put_json(content_url(content_id), payload) end
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)
- See: https://github.com/alphagov/publishing-api/blob/master/doc/api.md#post-v2contentcontent_idunpublish -
Parameters:
-
redirects
(Array
) -- (optional) Required if no alternative_path is given. An array of redirect values, ie: { path:, type:, destination: } -
unpublished_at
(Time
) -- (optional) The time the content was withdrawn. Ignored for types other than withdrawn -
locale
(String
) -- (optional) The content item locale. -
previous_version
(Integer
) -- (optional) A lock version number for optimistic locking. -
discard_drafts
(Boolean
) -- (optional) Whether to discard drafts on that item. Defaults to false. -
alternative_path
(String
) -- (optional) Alternative path to show on the page or redirect to. -
explanation
(String
) -- (optional) Text to show on the page. -
type
(String
) -- Either 'withdrawal', 'gone' or 'redirect'. -
content_id
(UUID
) --
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
def unpublish_url(content_id)
def unpublish_url(content_id) validate_content_id(content_id) "#{endpoint}/v2/content/#{content_id}/unpublish" end
def validate_content_id(content_id)
def validate_content_id(content_id) raise ArgumentError, "content_id cannot be nil" unless content_id end