publishing_platform_api_adapters 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9b05ed814403c8e76bb61a31e28e271636a959b364b91790c4db66480814d726
+  data.tar.gz: a6c23beead962d8c2db6830e3022d7876d783a917fc6d8b468ac00fcd07fd5bb
+SHA512:
+  metadata.gz: '06587180c50b7e88b24df754c3ace7d7d7202182d28d066736cba648f57260f46c86fa7d1ecb9e5ce5057ee00f3bc7b48f1530cf375161261ae8b621b375edd7'
+  data.tar.gz: 6dbd74d1d29c65369b5f605d29af19bc6404c901e55164997a70b3b4d74dfe57ad7d06d7e3477e2ae5f08600f366f8ad054902d3d54af9ae99080e3ac40cab12

data/README.md

@@ -0,0 +1,2 @@
+# Publishing Platform API Adapters
+A set of API adapters to work with the Publishing Platform APIs

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/publishing_platform_api/base.rb

@@ -0,0 +1,87 @@
+require_relative "json_client"
+require "cgi"
+require "null_logger"
+require "publishing_platform_location"
+require_relative "list_response"
+
+class PublishingPlatformApi::Base
+  class InvalidAPIURL < StandardError
+  end
+
+  extend Forwardable
+
+  def client
+    @client ||= create_client
+  end
+
+  def create_client
+    PublishingPlatformApi::JsonClient.new(options)
+  end
+
+  def_delegators :client,
+                 :get_json,
+                 :post_json,
+                 :put_json,
+                 :patch_json,
+                 :delete_json,
+                 :get_raw,
+                 :get_raw!,
+                 :put_multipart,
+                 :post_multipart
+
+  attr_reader :options
+
+  class << self
+    attr_writer :logger
+    attr_accessor :default_options
+  end
+
+  def self.logger
+    @logger ||= NullLogger.instance
+  end
+
+  def initialize(endpoint_url, options = {})
+    options[:endpoint_url] = endpoint_url
+    raise InvalidAPIURL unless endpoint_url =~ URI::RFC3986_Parser::RFC3986_URI
+
+    base_options = { logger: PublishingPlatformApi::Base.logger }
+    default_options = base_options.merge(PublishingPlatformApi::Base.default_options || {})
+    @options = default_options.merge(options)
+    self.endpoint = options[:endpoint_url]
+  end
+
+  def url_for_slug(slug, options = {})
+    "#{base_url}/#{slug}.json#{query_string(options)}"
+  end
+
+  def get_list(url)
+    get_json(url) do |r|
+      PublishingPlatformApi::ListResponse.new(r, self)
+    end
+  end
+
+private
+
+  attr_accessor :endpoint
+
+  def query_string(params)
+    return "" if params.empty?
+
+    param_pairs = params.sort.map { |key, value|
+      case value
+      when Array
+        value.map do |v|
+          "#{CGI.escape("#{key}[]")}=#{CGI.escape(v.to_s)}"
+        end
+      else
+        "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+      end
+    }.flatten
+
+    "?#{param_pairs.join('&')}"
+  end
+
+  def uri_encode(param)
+    Addressable::URI.encode(param.to_s)
+  end
+end

data/lib/publishing_platform_api/exceptions.rb

@@ -0,0 +1,116 @@
+module PublishingPlatformApi
+  # Abstract error class
+  class BaseError < StandardError
+    # Give Sentry extra context about this event
+    # https://docs.sentry.io/clients/ruby/context/
+    def sentry_context
+      {
+        # Make Sentry group exceptions by type instead of message, so all
+        # exceptions like `PublishingPlatformApi::TimedOutException` will get grouped as one
+        # error and not an error per URL.
+        fingerprint: [self.class.name],
+      }
+    end
+  end
+
+  class EndpointNotFound < BaseError; end
+
+  class TimedOutException < BaseError; end
+
+  class InvalidUrl < BaseError; end
+
+  class SocketErrorException < BaseError; end
+
+  # Superclass for all 4XX and 5XX errors
+  class HTTPErrorResponse < BaseError
+    attr_accessor :code, :error_details, :http_body
+
+    def initialize(code, message = nil, error_details = nil, http_body = nil)
+      super(message)
+      @code = code
+      @error_details = error_details
+      @http_body = http_body
+    end
+  end
+
+  # Superclass & fallback for all 4XX errors
+  class HTTPClientError < HTTPErrorResponse; end
+
+  class HTTPIntermittentClientError < HTTPClientError; end
+
+  class HTTPNotFound < HTTPClientError; end
+
+  class HTTPGone < HTTPClientError; end
+
+  class HTTPPayloadTooLarge < HTTPClientError; end
+
+  class HTTPUnauthorized < HTTPClientError; end
+
+  class HTTPForbidden < HTTPClientError; end
+
+  class HTTPConflict < HTTPClientError; end
+
+  class HTTPUnprocessableEntity < HTTPClientError; end
+
+  class HTTPBadRequest < HTTPClientError; end
+
+  class HTTPTooManyRequests < HTTPIntermittentClientError; end
+
+  # Superclass & fallback for all 5XX errors
+  class HTTPServerError < HTTPErrorResponse; end
+
+  class HTTPIntermittentServerError < HTTPServerError; end
+
+  class HTTPInternalServerError < HTTPServerError; end
+
+  class HTTPBadGateway < HTTPIntermittentServerError; end
+
+  class HTTPUnavailable < HTTPIntermittentServerError; end
+
+  class HTTPGatewayTimeout < HTTPIntermittentServerError; end
+
+  module ExceptionHandling
+    def build_specific_http_error(error, url, details = nil)
+      message = "URL: #{url}\nResponse body:\n#{error.http_body}"
+      code = error.http_code
+      error_class_for_code(code).new(code, message, details, error.http_body)
+    end
+
+    def error_class_for_code(code)
+      case code
+      when 400
+        PublishingPlatformApi::HTTPBadRequest
+      when 401
+        PublishingPlatformApi::HTTPUnauthorized
+      when 403
+        PublishingPlatformApi::HTTPForbidden
+      when 404
+        PublishingPlatformApi::HTTPNotFound
+      when 409
+        PublishingPlatformApi::HTTPConflict
+      when 410
+        PublishingPlatformApi::HTTPGone
+      when 413
+        PublishingPlatformApi::HTTPPayloadTooLarge
+      when 422
+        PublishingPlatformApi::HTTPUnprocessableEntity
+      when 429
+        PublishingPlatformApi::HTTPTooManyRequests
+      when (400..499)
+        PublishingPlatformApi::HTTPClientError
+      when 500
+        PublishingPlatformApi::HTTPInternalServerError
+      when 502
+        PublishingPlatformApi::HTTPBadGateway
+      when 503
+        PublishingPlatformApi::HTTPUnavailable
+      when 504
+        PublishingPlatformApi::HTTPGatewayTimeout
+      when (500..599)
+        PublishingPlatformApi::HTTPServerError
+      else
+        PublishingPlatformApi::HTTPErrorResponse
+      end
+    end
+  end
+end

data/lib/publishing_platform_api/json_client.rb

@@ -0,0 +1,201 @@
+require_relative "response"
+require_relative "exceptions"
+require_relative "version"
+require_relative "publishing_platform_headers"
+require "rest-client"
+require "null_logger"
+
+module PublishingPlatformApi
+  class JsonClient
+    include PublishingPlatformApi::ExceptionHandling
+
+    attr_accessor :logger, :options
+
+    def initialize(options = {})
+      if options[:disable_timeout] || options[:timeout].to_i.negative?
+        raise "It is no longer possible to disable the timeout."
+      end
+
+      @logger = options[:logger] || NullLogger.instance
+      @options = options
+    end
+
+    def self.default_request_headers
+      {
+        "Accept" => "application/json",
+        # PUBLISHING_PLATFORM_APP_NAME is set for all apps
+        "User-Agent" => "publishing_platform_api_adapters/#{PublishingPlatformApi::VERSION} (#{ENV['PUBLISHING_PLATFORM_APP_NAME']})",
+      }
+    end
+
+    def self.default_request_with_json_body_headers
+      default_request_headers.merge(json_body_headers)
+    end
+
+    def self.json_body_headers
+      {
+        "Content-Type" => "application/json",
+      }
+    end
+
+    DEFAULT_TIMEOUT_IN_SECONDS = 4
+
+    def get_raw!(url)
+      do_raw_request(:get, url)
+    end
+
+    def get_raw(url)
+      get_raw!(url)
+    end
+
+    def get_json(url, additional_headers = {}, &create_response)
+      do_json_request(:get, url, nil, additional_headers, &create_response)
+    end
+
+    def post_json(url, params = {}, additional_headers = {})
+      do_json_request(:post, url, params, additional_headers)
+    end
+
+    def put_json(url, params, additional_headers = {})
+      do_json_request(:put, url, params, additional_headers)
+    end
+
+    def patch_json(url, params, additional_headers = {})
+      do_json_request(:patch, url, params, additional_headers)
+    end
+
+    def delete_json(url, params = {}, additional_headers = {})
+      do_json_request(:delete, url, params, additional_headers)
+    end
+
+    def post_multipart(url, params)
+      r = do_raw_request(:post, url, params.merge(multipart: true))
+      Response.new(r)
+    end
+
+    def put_multipart(url, params)
+      r = do_raw_request(:put, url, params.merge(multipart: true))
+      Response.new(r)
+    end
+
+  private
+
+    def do_raw_request(method, url, params = nil)
+      do_request(method, url, params)
+    rescue RestClient::Exception => e
+      raise build_specific_http_error(e, url, nil)
+    end
+
+    # method: the symbolic name of the method to use, e.g. :get, :post
+    # url:    the request URL
+    # params: the data to send (JSON-serialised) in the request body
+    # additional_headers: headers to set on the request (in addition to the default ones)
+    # create_response: optional block to instantiate a custom response object
+    #                  from the Net::HTTPResponse
+    def do_json_request(method, url, params = nil, additional_headers = {}, &create_response)
+      begin
+        if params
+          additional_headers.merge!(self.class.json_body_headers)
+        end
+        response = do_request(method, url, (params.to_json if params), additional_headers)
+      rescue RestClient::Exception => e
+        # Attempt to parse the body as JSON if possible
+        error_details = begin
+          e.http_body ? JSON.parse(e.http_body) : nil
+        rescue JSON::ParserError
+          nil
+        end
+        raise build_specific_http_error(e, url, error_details)
+      end
+
+      # If no custom response is given, just instantiate Response
+      create_response ||= proc { |r| Response.new(r) }
+      create_response.call(response)
+    end
+
+    # Take a hash of parameters for Request#execute; return a hash of
+    # parameters with authentication information included
+    def with_auth_options(method_params)
+      if @options[:bearer_token]
+        headers = method_params[:headers] || {}
+        method_params.merge(headers: headers.merge(
+          "Authorization" => "Bearer #{@options[:bearer_token]}",
+        ))
+      elsif @options[:basic_auth]
+        method_params.merge(
+          user: @options[:basic_auth][:user],
+          password: @options[:basic_auth][:password],
+        )
+      else
+        method_params
+      end
+    end
+
+    # Take a hash of parameters for Request#execute; return a hash of
+    # parameters with timeouts included
+    def with_timeout(method_params)
+      method_params.merge(
+        timeout: options[:timeout] || DEFAULT_TIMEOUT_IN_SECONDS,
+        open_timeout: options[:timeout] || DEFAULT_TIMEOUT_IN_SECONDS,
+      )
+    end
+
+    def with_headers(method_params, default_headers, additional_headers)
+      method_params.merge(
+        headers: default_headers
+          .merge(method_params[:headers] || {})
+          .merge(PublishingPlatformApi::PublishingPlatformHeaders.headers)
+          .merge(additional_headers),
+      )
+    end
+
+    def with_ssl_options(method_params)
+      method_params.merge(
+        # This is the default value anyway, but we should probably be explicit
+        verify_ssl: OpenSSL::SSL::VERIFY_NONE,
+      )
+    end
+
+    def do_request(method, url, params = nil, additional_headers = {})
+      loggable = { request_uri: url, start_time: Time.now.to_f, publishing_platform_request_id: PublishingPlatformApi::PublishingPlatformHeaders.headers[:publishing_platform_request_id] }.compact
+      start_logging = loggable.merge(action: "start")
+      logger.debug start_logging.to_json
+
+      method_params = {
+        method:,
+        url:,
+      }
+
+      method_params[:payload] = params
+      method_params = with_timeout(method_params)
+      method_params = with_headers(method_params, self.class.default_request_headers, additional_headers)
+      method_params = with_auth_options(method_params)
+      if URI.parse(url).is_a? URI::HTTPS
+        method_params = with_ssl_options(method_params)
+      end
+
+      ::RestClient::Request.execute(method_params)
+    rescue Errno::ECONNREFUSED => e
+      logger.error loggable.merge(status: "refused", error_message: e.message, error_class: e.class.name, end_time: Time.now.to_f).to_json
+      raise PublishingPlatformApi::EndpointNotFound, "Could not connect to #{url}"
+    rescue RestClient::Exceptions::Timeout => e
+      logger.error loggable.merge(status: "timeout", error_message: e.message, error_class: e.class.name, end_time: Time.now.to_f).to_json
+      raise PublishingPlatformApi::TimedOutException, e.message
+    rescue URI::InvalidURIError => e
+      logger.error loggable.merge(status: "invalid_uri", error_message: e.message, error_class: e.class.name, end_time: Time.now.to_f).to_json
+      raise PublishingPlatformApi::InvalidUrl, e.message
+    rescue RestClient::Exception => e
+      # Log the error here, since we have access to loggable, but raise the
+      # exception up to the calling method to deal with
+      loggable.merge!(status: e.http_code, end_time: Time.now.to_f, body: e.http_body)
+      logger.warn loggable.to_json
+      raise
+    rescue Errno::ECONNRESET => e
+      logger.error loggable.merge(status: "connection_reset", error_message: e.message, error_class: e.class.name, end_time: Time.now.to_f).to_json
+      raise PublishingPlatformApi::TimedOutException, e.message
+    rescue SocketError => e
+      logger.error loggable.merge(status: "socket_error", error_message: e.message, error_class: e.class.name, end_time: Time.now.to_f).to_json
+      raise PublishingPlatformApi::SocketErrorException, e.message
+    end
+  end
+end

data/lib/publishing_platform_api/list_response.rb

@@ -0,0 +1,89 @@
+require "json"
+require "publishing_platform_api/response"
+require "link_header"
+
+module PublishingPlatformApi
+  # Response class for lists of multiple items.
+  #
+  # This expects responses to be in a common format, with the list of results
+  # contained under the `results` key. The response may also have previous and
+  # subsequent pages, indicated by entries in the response's `Link` header.
+  class ListResponse < Response
+    # The ListResponse is instantiated with a reference back to the API client,
+    # so it can make requests for the subsequent pages
+    def initialize(response, api_client, options = {})
+      super(response, options)
+      @api_client = api_client
+    end
+
+    # Pass calls to `self.each` to the `results` sub-object, so we can iterate
+    # over the response directly
+    def_delegators :results, :each, :to_ary
+
+    def results
+      to_hash["results"]
+    end
+
+    def has_next_page?
+      !page_link("next").nil?
+    end
+
+    def next_page
+      # This shouldn't be a performance problem, since the cache will generally
+      # avoid us making multiple requests for the same page, but we shouldn't
+      # allow the data to change once it's already been loaded, so long as we
+      # retain a reference to any one page in the sequence
+      @next_page ||= if has_next_page?
+                       @api_client.get_list page_link("next").href
+                     end
+    end
+
+    def has_previous_page?
+      !page_link("previous").nil?
+    end
+
+    def previous_page
+      # See the note in `next_page` for why this is memoised
+      @previous_page ||= if has_previous_page?
+                           @api_client.get_list(page_link("previous").href)
+                         end
+    end
+
+    # Transparently get all results across all pages. Compare this with #each
+    # or #results which only iterate over the current page.
+    #
+    # Example:
+    #
+    #   list_response.with_subsequent_pages.each do |result|
+    #     ...
+    #   end
+    #
+    # or:
+    #
+    #   list_response.with_subsequent_pages.count
+    #
+    # Pages of results are fetched on demand. When iterating, that means
+    # fetching pages as results from the current page are exhausted. If you
+    # invoke a method such as #count, this method will fetch all pages at that
+    # point. Note that the responses are stored so subsequent pages will not be
+    # loaded multiple times.
+    def with_subsequent_pages
+      Enumerator.new do |yielder|
+        each { |i| yielder << i }
+        if has_next_page?
+          next_page.with_subsequent_pages.each { |i| yielder << i }
+        end
+      end
+    end
+
+  private
+
+    def link_header
+      @link_header ||= LinkHeader.parse @http_response.headers[:link]
+    end
+
+    def page_link(rel)
+      link_header.find_link(["rel", rel])
+    end
+  end
+end

data/lib/publishing_platform_api/middleware/publishing_platform_header_sniffer.rb

@@ -0,0 +1,21 @@
+require_relative "../publishing_platform_headers"
+
+module PublishingPlatformApi
+  class PublishingPlatformHeaderSniffer
+    def initialize(app, header_name)
+      @app = app
+      @header_name = header_name
+    end
+
+    def call(env)
+      PublishingPlatformApi::PublishingPlatformHeaders.set_header(readable_name, env[@header_name])
+      @app.call(env)
+    end
+
+  private
+
+    def readable_name
+      @header_name.sub(/^HTTP_/, "").downcase.to_sym
+    end
+  end
+end

data/lib/publishing_platform_api/publishing_api.rb

@@ -0,0 +1,222 @@
+require_relative "base"
+require_relative "exceptions"
+
+# Adapter for the Publishing API.
+#
+# @api documented
+class PublishingPlatformApi::PublishingApi < PublishingPlatformApi::Base
+  class NoLiveVersion < PublishingPlatformApi::BaseError; end
+
+  # Put a content item
+  #
+  # @param content_id [UUID]
+  # @param payload [Hash] A valid content item  
+  def put_content(content_id, payload)
+    put_json(content_url(content_id), payload)
+  end
+
+  # Return a content item
+  #
+  # Raises exception if the item doesn't exist.
+  #
+  # @param content_id [UUID]
+  # @param params [Hash]
+  #
+  # @return [PublishingPlatformApi::Response] a content item
+  #
+  # @raise [HTTPNotFound] when the content item is not found
+  def get_content(content_id, params = {})
+    get_json(content_url(content_id, params))
+  end
+
+  # Publish a content item
+  #
+  # The publishing-api will "publish" a draft item, so that it will be visible
+  # on the public site.
+  #
+  # @param content_id [UUID]
+  # @param update_type [String] Either 'major', 'minor' or 'republish'
+  # @param options [Hash]
+  def publish(content_id, update_type = nil, options = {})
+    params = {
+      update_type:,
+    }
+
+    optional_keys = %i[previous_version]
+
+    params = merge_optional_keys(params, options, optional_keys)
+
+    post_json(publish_url(content_id), params)
+  end
+
+  # 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
+  #
+  # @param content_id [UUID]
+  # @param options [Hash]
+  def republish(content_id, options = {})
+    optional_keys = %i[previous_version]
+
+    params = merge_optional_keys({}, options, optional_keys)
+
+    post_json(republish_url(content_id), params)
+  end
+
+  # Unpublish a content item
+  #
+  # The publishing API will "unpublish" a live item, to remove it from the public
+  # site, or update an existing unpublishing.
+  #
+  # @param content_id [UUID]
+  # @param type [String] Either 'withdrawal', 'gone' or 'redirect'.
+  # @param explanation [String] (optional) Text to show on the page.
+  # @param alternative_path [String] (optional) Alternative path to show on the page or redirect to.
+  # @param discard_drafts [Boolean] (optional) Whether to discard drafts on that item.  Defaults to false.
+  # @param previous_version [Integer] (optional) A lock version number for optimistic locking.
+  # @param unpublished_at [Time] (optional) The time the content was withdrawn. Ignored for types other than withdrawn
+  # @param redirects [Array] (optional) Required if no alternative_path is given. An array of redirect values, ie: { path:, type:, destination: }
+  def unpublish(content_id, type:, explanation: nil, alternative_path: nil, discard_drafts: false, allow_draft: false, previous_version: 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[:unpublished_at] = unpublished_at.utc.iso8601 if unpublished_at
+    params[:redirects] = redirects if redirects
+
+    post_json(unpublish_url(content_id), params)
+  end
+
+  # Discard a draft
+  #
+  # Deletes the draft content item.
+  #
+  # @param options [Hash]
+  # @option options [Integer] previous_version used to ensure the request is discarding the latest lock version of the draft
+  def discard_draft(content_id, options = {})
+    optional_keys = %i[previous_version]
+
+    params = merge_optional_keys({}, options, optional_keys)
+
+    post_json(discard_url(content_id), params)
+  end
+
+  # Patch the links of a content item
+  #
+  # @param content_id [UUID]
+  # @param params [Hash]
+  # @option params [Hash] links A "links hash"
+  # @option params [Integer] previous_version 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)  
+  # @example
+  #
+  #   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
+  #   )
+  #
+  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
+
+  # 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.
+  #
+  # @param 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.
+  #
+  # @example
+  #
+  #   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'],
+  #     order: '-public_updated_at'
+  #   )
+  def get_content_items(params)
+    query = query_string(params)
+    get_json("#{endpoint}/content#{query}")
+  end
+
+  # Reserves a path for a publishing application
+  #
+  # Returns success or failure only.
+  #
+  # @param payload [Hash]
+  # @option payload [Hash] publishing_app The publishing application, like `content-tagger`
+  def put_path(base_path, payload)
+    url = "#{endpoint}/paths#{base_path}"
+    put_json(url, payload)
+  end
+
+  def unreserve_path(base_path, publishing_app)
+    payload = { publishing_app: }
+    delete_json(unreserve_url(base_path), payload)
+  end
+
+private
+
+  def content_url(content_id, params = {})
+    validate_content_id(content_id)
+    query = query_string(params)
+    "#{endpoint}/content/#{content_id}#{query}"
+  end
+
+  def links_url(content_id)
+    validate_content_id(content_id)
+    "#{endpoint}/links/#{content_id}"
+  end
+
+  def publish_url(content_id)
+    validate_content_id(content_id)
+    "#{endpoint}/content/#{content_id}/publish"
+  end
+
+  def republish_url(content_id)
+    validate_content_id(content_id)
+    "#{endpoint}/content/#{content_id}/republish"
+  end
+
+  def unpublish_url(content_id)
+    validate_content_id(content_id)
+    "#{endpoint}/content/#{content_id}/unpublish"
+  end
+
+  def discard_url(content_id)
+    validate_content_id(content_id)
+    "#{endpoint}/content/#{content_id}/discard-draft"
+  end
+
+  def unreserve_url(base_path)
+    "#{endpoint}/paths#{base_path}"
+  end
+
+  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 validate_content_id(content_id)
+    raise ArgumentError, "content_id cannot be nil" unless content_id
+  end
+end

data/lib/publishing_platform_api/publishing_platform_headers.rb

@@ -0,0 +1,23 @@
+module PublishingPlatformApi
+  class PublishingPlatformHeaders
+    class << self
+      def set_header(header_name, value)
+        header_data[header_name] = value
+      end
+
+      def headers
+        header_data.reject { |_k, v| v.nil? || v.empty? }
+      end
+
+      def clear_headers
+        Thread.current[:headers] = {}
+      end
+
+    private
+
+      def header_data
+        Thread.current[:headers] ||= {}
+      end
+    end
+  end
+end

data/lib/publishing_platform_api/railtie.rb

@@ -0,0 +1,30 @@
+require_relative "middleware/publishing_platform_header_sniffer"
+
+module PublishingPlatformApi
+  class Railtie < Rails::Railtie
+    initializer "publishing_platform_api.initialize_publishing_platform_request_id_sniffer" do |app|
+      Rails.logger.debug "Using middleware PublishingPlatformApi::PublishingPlatformHeaderSniffer to sniff for PublishingPlatform-Request-Id header"
+      app.middleware.use PublishingPlatformApi::PublishingPlatformHeaderSniffer, "HTTP_PUBLISHING_PLATFORM_REQUEST_ID"
+    end
+
+    initializer "publishing_platform_api.initialize_publishing_platform_original_url_sniffer" do |app|
+      Rails.logger.debug "Using middleware PublishingPlatformApi::PublishingPlatformHeaderSniffer to sniff for PublishingPlatform-Original-Url header"
+      app.middleware.use PublishingPlatformApi::PublishingPlatformHeaderSniffer, "HTTP_PUBLISHING_PLATFORM_ORIGINAL_URL"
+    end
+
+    initializer "publishing_platform_api.initialize_publishing_platform_authenticated_user_sniffer" do |app|
+      Rails.logger.debug "Using middleware PublishingPlatformApi::PublishingPlatformHeaderSniffer to sniff for X-PublishingPlatform-Authenticated-User header"
+      app.middleware.use PublishingPlatformApi::PublishingPlatformHeaderSniffer, "HTTP_X_PUBLISHING_PLATFORM_AUTHENTICATED_USER"
+    end
+
+    initializer "publishing_platform_api.initialize_publishing_platform_authenticated_user_organisation_sniffer" do |app|
+      Rails.logger.debug "Using middleware PublishingPlatformApi::PublishingPlatformHeaderSniffer to sniff for X-PublishingPlatform-Authenticated-User-Organisation header"
+      app.middleware.use PublishingPlatformApi::PublishingPlatformHeaderSniffer, "HTTP_X_PUBLISHING_PLATFORM_AUTHENTICATED_USER_ORGANISATION"
+    end
+
+    initializer "publishing_platform_api.initialize_publishing_platform_content_id_sniffer" do |app|
+      Rails.logger.debug "Using middleware PublishingPlatformApi::PublishingPlatformHeaderSniffer to sniff for PublishingPlatform-Auth-Bypass-Id header"
+      app.middleware.use PublishingPlatformApi::PublishingPlatformHeaderSniffer, "HTTP_PUBLISHING_PLATFORM_AUTH_BYPASS_ID"
+    end
+  end
+end

data/lib/publishing_platform_api/response.rb

@@ -0,0 +1,183 @@
+require "json"
+require "forwardable"
+
+module PublishingPlatformApi
+  # This wraps an HTTP response with a JSON body.
+  #
+  # Responses can be configured to use relative URLs for `web_url` properties.
+  # API endpoints should return absolute URLs so that they make sense outside of the
+  # Publishing Platform context.  However on internal systems we want to present relative URLs.
+  # By specifying a base URI, this will convert all matching web_urls into relative URLs
+  # This is useful on non-canonical frontends, such as those in staging environments.
+  #
+  # Example:
+  #
+  #   r = Response.new(response, web_urls_relative_to: "https://www.publishing-platform.co.uk")
+  #   r['results'][0]['web_url']
+  #   => "/bank-holidays"
+  class Response
+    extend Forwardable
+    include Enumerable
+
+    class CacheControl < Hash
+      PATTERN = /([-a-z]+)(?:\s*=\s*([^,\s]+))?,?+/i
+
+      def initialize(value = nil)
+        super()
+        parse(value)
+      end
+
+      def public?
+        self["public"]
+      end
+
+      def private?
+        self["private"]
+      end
+
+      def no_cache?
+        self["no-cache"]
+      end
+
+      def no_store?
+        self["no-store"]
+      end
+
+      def must_revalidate?
+        self["must-revalidate"]
+      end
+
+      def proxy_revalidate?
+        self["proxy-revalidate"]
+      end
+
+      def max_age
+        self["max-age"].to_i if key?("max-age")
+      end
+
+      def reverse_max_age
+        self["r-maxage"].to_i if key?("r-maxage")
+      end
+      alias_method :r_maxage, :reverse_max_age
+
+      def shared_max_age
+        self["s-maxage"].to_i if key?("r-maxage")
+      end
+      alias_method :s_maxage, :shared_max_age
+
+      def to_s
+        directives = []
+        values = []
+
+        each do |key, value|
+          if value == true
+            directives << key
+          elsif value
+            values << "#{key}=#{value}"
+          end
+        end
+
+        (directives.sort + values.sort).join(", ")
+      end
+
+    private
+
+      def parse(header)
+        return if header.nil? || header.empty?
+
+        header.scan(PATTERN).each do |name, value|
+          self[name.downcase] = value || true
+        end
+      end
+    end
+
+    def_delegators :to_hash, :[], :"<=>", :each, :dig
+
+    def initialize(http_response, options = {})
+      @http_response = http_response
+      @web_urls_relative_to = options[:web_urls_relative_to] ? URI.parse(options[:web_urls_relative_to]) : nil
+    end
+
+    def raw_response_body
+      @http_response.body
+    end
+
+    def code
+      # Return an integer code for consistency with HTTPErrorResponse
+      @http_response.code
+    end
+
+    def headers
+      @http_response.headers
+    end
+
+    def expires_at
+      if headers[:date] && cache_control.max_age
+        response_date = Time.parse(headers[:date])
+        response_date + cache_control.max_age
+      elsif headers[:expires]
+        Time.parse(headers[:expires])
+      end
+    end
+
+    def expires_in
+      return unless headers[:date]
+
+      age = Time.now.utc - Time.parse(headers[:date])
+
+      if cache_control.max_age
+        cache_control.max_age - age.to_i
+      elsif headers[:expires]
+        Time.parse(headers[:expires]).to_i - Time.now.utc.to_i
+      end
+    end
+
+    def cache_control
+      @cache_control ||= CacheControl.new(headers[:cache_control])
+    end
+
+    def to_hash
+      parsed_content
+    end
+
+    def parsed_content
+      @parsed_content ||= transform_parsed(JSON.parse(@http_response.body))
+    end
+
+    def present?
+      true
+    end
+
+    def blank?
+      false
+    end
+
+  private
+
+    def transform_parsed(value)
+      return value if @web_urls_relative_to.nil?
+
+      case value
+      when Hash
+        Hash[value.map do |k, v|
+          # NOTE: Don't bother transforming if the value is nil
+          if k == "web_url" && v
+            # Use relative URLs to route when the web_url value is on the
+            # same domain as the site root. Note that we can't just use the
+            # `route_to` method, as this would give us technically correct
+            # but potentially confusing `//host/path` URLs for URLs with the
+            # same scheme but different hosts.
+            relative_url = @web_urls_relative_to.route_to(v)
+            [k, relative_url.host ? v : relative_url.to_s]
+          else
+            [k, transform_parsed(v)]
+          end
+        end]
+      when Array
+        value.map { |v| transform_parsed(v) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/publishing_platform_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PublishingPlatformApi
+  VERSION = "0.1.0"
+end

data/lib/publishing_platform_api.rb

@@ -0,0 +1,20 @@
+require "addressable"
+require "publishing_platform_location"
+require "time"
+require "publishing_platform_api/publishing_api"
+
+# @api documented
+module PublishingPlatformApi
+  # Creates a PublishingPlatformApi::PublishingApi adapter
+  #
+  # This will set a bearer token if a PUBLISHING_API_BEARER_TOKEN environment
+  # variable is set
+  #
+  # @return [PublishingPlatformApi::PublishingApi]
+  def self.publishing_api(options = {})
+    PublishingPlatformApi::PublishingApi.new(
+      PublishingPlatformLocation.find("publishing-api"),
+      { bearer_token: ENV["PUBLISHING_API_BEARER_TOKEN"] }.merge(options),
+    )
+  end
+end

data/lib/publishing_platform_api_adapters.rb

@@ -0,0 +1,3 @@
+require "publishing_platform_api/railtie" if defined?(Rails)
+require "publishing_platform_api/exceptions"
+require "publishing_platform_api"

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: publishing_platform_api_adapters
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Publishing Platform
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-07-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: link_header
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: null_logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: publishing_platform_location
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: publishing_platform_rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Adapters to work with Publishing Platform APIs
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/publishing_platform_api.rb
+- lib/publishing_platform_api/base.rb
+- lib/publishing_platform_api/exceptions.rb
+- lib/publishing_platform_api/json_client.rb
+- lib/publishing_platform_api/list_response.rb
+- lib/publishing_platform_api/middleware/publishing_platform_header_sniffer.rb
+- lib/publishing_platform_api/publishing_api.rb
+- lib/publishing_platform_api/publishing_platform_headers.rb
+- lib/publishing_platform_api/railtie.rb
+- lib/publishing_platform_api/response.rb
+- lib/publishing_platform_api/version.rb
+- lib/publishing_platform_api_adapters.rb
+homepage: 
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key: 
+specification_version: 4
+summary: Adapters to work with Publishing Platform APIs
+test_files: []