confluence-rest-api 1.0.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6ef648c1789440d8b0568c147ecfa0f73977892eaeed56aae36a22b2d2f97505
+  data.tar.gz: 5732c846ff1dda66a7ca5a63939551088cf9906fc10e78efdbcff2d7748b7f5d
+SHA512:
+  metadata.gz: b35aeb68b573092496b57cb5dfb4156dc551ac45bbb156485bd8815a99a3a5f6922ce1cc8243b734d20774293f281fbce650d24dc2402bba4d93fa3b83d64e37
+  data.tar.gz: f9e68dbdfaaa568b97f154cc223e3969c3e98abb63cba274c5078fb7e5975ae4fc397b9256b8d339c05478470fe7f9c950d9186c57089f98df2ccc99a70c68ba

data/README.md

@@ -0,0 +1,131 @@
+# Ruby Confluence REST API Client
+
+[![Gem Version](https://badge.fury.io/rb/confluence-rest-api.svg)](https://badge.fury.io/rb/confluence-rest-api)
+### Installation
+```cassandraql
+gem install confluence-rest-api
+```
+### Usage
+```ruby
+require 'confluence-rest-api'
+
+rest_server = 'https://myserver.com'
+user_name   = 'username'
+password    = 'password'
+space_key   = 'space'
+
+client  = ConfluenceClient.new(rest_server, user_name, password)
+
+#################################
+# Query an existing page by title
+#################################
+
+page = PageObject.new('page_title', space_key)
+if page.id.nil? 
+    puts '*** WARNING: Unable to open page: page_title'
+else
+    puts "Body:         #{page.rendered_body}"
+    puts "Fully styled  #{page.styled_view}"
+    puts "ID:           #{page.id}"
+    puts "Status:       #{page.status}"
+    puts "Version:      #{page.version}"
+    puts "Created By:   #{page.created_by}"
+    puts "Date Created: #{page.created}"
+    puts "Date Updated: #{page.last_update}"
+    puts "Page URL:     #{page.url}"
+end
+
+###############################
+# Query an existing page by id
+###############################
+
+page = PageObject.new(123456789, space_key)
+if page.title.nil? 
+    puts '*** WARNING: Unable to open page with id: 123456789'
+else
+    puts "Body:         #{page.rendered_body}"
+    puts "Fully styled  #{page.styled_view}"
+    puts "ID:           #{page.id}"
+    puts "Status:       #{page.status}"
+    puts "Version:      #{page.version}"
+    puts "Created By:   #{page.created_by}"
+    puts "Date Created: #{page.created}"
+    puts "Date Updated: #{page.last_update}"
+    puts "Page URL:     #{page.url}"
+end
+
+###########################################################
+# Create a new page with a page titled "Home" as its parent
+###########################################################
+
+home_page = PageObject.new('Home', space_key)
+unless home_page.id.nil?
+  client.create_page_with_parent('My Page Title', space_key, 'My Page Body Content', home_page.id)
+end
+
+#############################
+# Add an attachment to a page
+#############################
+
+page_obj = PageObject.new('My Page Title', space_key)
+unless page_obj.id.nil?
+  img_base_name = 'my/image/location'
+  image = 'my_image.png'
+  if page_obj.attach_binary_file(image, img_base_name).nil?
+    puts "*** WARNING: Image attachment #{image} for #{title} was not successful."
+  else
+    puts "Image attachment #{image} for #{title} was successful."
+  end
+end
+
+##################################
+# Remove an attachment from a page
+##################################
+
+page_obj = PageObject.new('My Page Title', space_key)
+id = page_obj.attachment_id('my_image.png')
+if id.nil?
+  puts "Attachment doesn't exist."
+elsif page_obj.delete_attachment(id).nil?
+    puts "*** WARNING: Attachment with ID #{id} was not deleted."
+else
+    puts "Attachment with ID #{id} was deleted"
+end
+
+
+##################################################
+# Get an array listing of the page attachment data
+##################################################
+page_obj = PageObject.new('My Page Title', space_key)
+att_array = get_all_attachments(page_obj.id)
+att_array.each do |line|
+  entry_hash = line.to_hash
+  title = entry_hash["title"]
+  uri   = entry_hash["_links"]["download"]
+  puts "Attachment title: #{title}"
+  puts "Attachment link : #{uri}"
+end
+
+######################################################
+# Save all attachments of a page to the given location
+######################################################
+page_obj = PageObject.new('My Page Title', space_key)
+page_obj.save_file_attachments(page_obj.id, './')
+
+###############
+# Delete a page
+###############
+
+page_obj = PageObject.new('My Page Title', space_key)
+if page_obj.delete_page(page_obj.id).nil?
+  puts "*** WARNING: Page with ID #{page_obj.id} was not deleted."
+else
+  puts "Page with ID #{page_obj.id} was deleted."
+end
+
+
+````
+
+### TODO
+1. Add tests
+

data/confluence-rest-api.gemspec

@@ -0,0 +1,14 @@
+Gem::Specification.new do |s|
+  s.name    = %q{confluence-rest-api}
+  s.version = "1.0.6"
+  s.date    = %q{2020-04-17}
+  s.summary = %q{Ruby REST API Client to create, update, and view pages}
+  s.authors = "Gregory J. Miller"
+  s.files   = [
+      "lib/confluence-rest-api.rb", "lib/confluence.rb", "lib/page.rb", "lib/storage_format.rb", "README.md", "confluence-rest-api.gemspec"
+  ]
+  s.license       = "MIT"
+  s.homepage      = "https://github.com/grmi64/confluence-rest-api"
+  s.add_runtime_dependency 'rest-client', '~> 2.0', '>= 2.0.0'
+
+end

data/lib/confluence-rest-api.rb

@@ -0,0 +1,4 @@
+require 'confluence'
+require 'page'
+require 'storage_format'
+

data/lib/confluence.rb

@@ -0,0 +1,91 @@
+require 'rest-client'
+require 'json'
+
+class ConfluenceClient
+
+  def initialize(url, name, password)
+    @@conf_url = url
+    @@login    = name
+    @@pwd      = password
+    @@urn      = 'rest/api/content'
+  end
+
+  def create_page_with_parent(title, spacekey, content, parentid)
+
+    page_meta = { type:     'create_page_with_parent',
+                  title:    title,
+                  spacekey: spacekey,
+                  content:  content,
+                  parentid: parentid }
+
+    create_page(PagePayload.new(page_meta).page_format)
+
+  end
+
+  def update_page_with_parent(page_obj, parent_page_obj, spacekey, content)
+
+    version = page_obj.version + 1
+
+    page_meta = { type:     'update_page_with_parent',
+                  pageid:   page_obj.id,
+                  parentid: parent_page_obj.id,
+                  title:    page_obj.title,
+                  spacekey: spacekey,
+                  content:  content,
+                  version:  version }
+
+    update_page(PagePayload.new(page_meta).page_format, page_obj.id)
+
+  end
+
+  def create_page_with_no_parent(title, spacekey, content)
+
+    page_meta = { type:     'create_page_with_no_parent',
+                  title:    title,
+                  spacekey: spacekey,
+                  content:  content }
+
+    create_page(PagePayload.new(page_meta).page_format)
+
+  end
+
+  def update_page_with_no_parent(page_obj, spacekey, content)
+
+    version = page_obj.version + 1
+
+    page_meta = { type:     'update_page_with_no_parent',
+                  pageid:   page_obj.id,
+                  title:    page_obj.title,
+                  spacekey: spacekey,
+                  content:  content,
+                  version:  version }
+
+    update_page(PagePayload.new(page_meta).page_format, page_obj.id)
+
+  end
+
+  private
+
+  def create_page(payload)
+
+    url = "#{@@conf_url}/#{@@urn}?os_username=#{@@login}&os_password=#{@@pwd}"
+    begin
+      RestClient.post url, payload, :content_type => 'application/json'
+    rescue RestClient::ExceptionWithResponse => error
+      puts '*** ERROR: RestClient.post failed'
+      pp error
+    end
+  end
+
+  def update_page(payload, id)
+
+    url = "#{@@conf_url}/#{@@urn}/#{id}?os_username=#{@@login}&os_password=#{@@pwd}"
+    begin
+      RestClient.put url, payload, :content_type => 'application/json', :accept => 'json'
+    rescue RestClient::ExceptionWithResponse => error
+      puts '*** ERROR: RestClient.put failed'
+      puts error
+    end
+  end
+
+end

data/lib/page.rb

@@ -0,0 +1,225 @@
+require 'nokogiri'
+
+class PageObject < ConfluenceClient
+
+  attr_reader :title, :id, :version, :status, :created, :created_by, :last_updated
+
+  def initialize(title_or_id, spacekey)
+    if title_or_id.is_a? Integer
+      @title, @id, @version, @status, @created, @created_by, @last_updated, @url = get_page_info_by_id(title_or_id.to_s, spacekey)
+    else
+      @title, @id, @version, @status, @created, @created_by, @last_updated, @url = get_page_info_by_title(title_or_id, spacekey)
+    end
+  end
+
+  def url
+    unless @url.nil?
+      @@conf_url + @url
+    end
+  end
+
+  #####################################################
+  # Includes entire HTML render (including HEADER etc.)
+  #####################################################
+  def styled_view
+    begin
+      res = RestClient.get "#{@@conf_url}/#{@@urn}/#{@id}", {params: {
+          :expand => 'body.styled_view', :os_username => @@login, :os_password => @@pwd
+      }}
+    rescue RestClient::ExceptionWithResponse => e
+      puts Nokogiri.XML(e.response)
+    end
+    JSON.parse(res)['body']['styled_view']['value']
+  end
+
+  ##################################################
+  # Includes only the rendered HTML BODY of the page
+  ##################################################
+  def rendered_body
+    begin
+      res = RestClient.get "#{@@conf_url}/#{@@urn}/#{@id}", {params: {
+          :expand => 'body.view', :os_username => @@login, :os_password => @@pwd
+      }}
+    rescue RestClient::ExceptionWithResponse => e
+      puts Nokogiri.XML(e.response)
+    end
+    JSON.parse(res)['body']['view']['value']
+  end
+
+  def storage_format
+    begin
+      res = RestClient.get "#{@@conf_url}/#{@@urn}/#{@id}", {params: {
+          :expand => 'body.storage', :os_username => @@login, :os_password => @@pwd
+      }}
+    rescue RestClient::ExceptionWithResponse => e
+      puts Nokogiri.XML(e.response)
+    end
+    JSON.parse(res)['body']['storage']['value']
+  end
+
+  def delete_page(page_id)
+    begin
+      RestClient.delete "#{@@conf_url}/#{@@urn}/#{page_id}", {params: {
+          :os_username => @@login, :os_password => @@pwd
+      }}
+    rescue RestClient::ExceptionWithResponse => e
+      puts Nokogiri.XML(e.response)
+      return nil
+    end
+    true
+  end
+
+  # Return an array of all page attachment information
+  def get_all_attachments(page_id)
+
+    url = "#{@@conf_url}/#{@@urn}/#{page_id}/child/attachment?os_username=#{@@login}&os_password=#{@@pwd}&status=current"
+
+    begin
+      atts = RestClient.get url, :content_type => 'application/json', :accept => 'json'
+    rescue RestClient::ExceptionWithResponse => e
+      puts Nokogiri.XML(e.response)
+      nil
+    end
+
+    unless atts.nil?
+      JSON.parse(atts)["results"]
+    end
+  end
+
+  def attach_binary_file(file_name, file_basename)
+
+    if File.exist?("#{file_basename}/#{file_name}")
+      payload = {
+          multipart: true,
+          file: File.new("#{file_basename}/#{file_name}", 'rb'),
+          comment: 'Automated Ruby import',
+          minorEdit: true
+      }
+      url_mod = "#{@@conf_url}/#{@@urn}/#{@id}/child/attachment?os_username=#{@@login}&os_password=#{@@pwd}"
+      begin
+        RestClient.post(url_mod, payload, {"X-Atlassian-Token" => "nocheck"})
+        true
+      rescue RestClient::ExceptionWithResponse => e
+        puts Nokogiri.XML(e.response)
+        nil
+      end
+    else
+      puts "*** WARNING: File can't be found for #{file_basename}/#{file_name}"
+      nil
+    end
+  end
+
+  def delete_attachment(attach_id)
+    begin
+      RestClient.delete "#{@@conf_url}/#{@@urn}/#{attach_id}", {params: {
+          :os_username => @@login, :os_password => @@pwd
+      }}
+    rescue RestClient::ExceptionWithResponse => e
+      puts Nokogiri.XML(e.response)
+      return nil
+    end
+    true
+  end
+
+  def attachment_id(attachment_name)
+
+    fname = attachment_name.dup
+    fname = CGI.escape(fname)
+
+    begin
+      response = RestClient.get "#{@@conf_url}/#{@@urn}/#{@id}/child/attachment", {params: {
+          :filename => fname, 'os_username' => @@login, 'os_password' => @@pwd
+      }}
+
+      response = JSON.parse(response)
+      if response['results'].any?
+        return response['results'][0]['id']
+      end
+    rescue RestClient::ExceptionWithResponse => e
+      puts Nokogiri.XML(e.response)
+    end
+    nil
+  end
+
+  def save_file_attachments(page_id, storage_path)
+    if File.writable? storage_path
+      att_array = get_all_attachments(page_id)
+
+      att_array.each do |line|
+        download_hash = line.to_hash
+        title = download_hash["title"]
+        url   = @@conf_url + download_hash["_links"]["download"] + "&os_username=#{@@login}&os_password=#{@@pwd}"
+
+        File.open(storage_path + title, 'wb') {|f|
+          block = proc { |response|
+            response.read_body do |chunk|
+              f.write chunk.to_s
+            end
+          }
+          RestClient::Request.execute(method: :get,
+                                      url: url,
+                                      block_response: block)
+        }
+      end
+    else
+      puts "*** ERROR: Cannot write to path: #{storage_path}"
+      puts "   Skipping."
+      return false
+    end
+    true
+  end
+
+  ##################################################################
+  private
+  ##################################################################
+
+  # Here we can return various metadata for a given page.
+  def get_page_info_by_title(title, spacekey)
+    begin
+      res = RestClient.get "#{@@conf_url}/#{@@urn}", {params: {
+          :title => title, :spaceKey => spacekey, :os_username => @@login, :os_password => @@pwd, :expand => 'version,history'
+      }}
+    rescue RestClient::ExceptionWithResponse => e
+      puts Nokogiri.XML(e.response)
+    end
+    if res.nil? || JSON.parse(res)['results'][0].nil?
+      puts '*** WARNING: Page ID not found.'
+      puts "             Page: #{title}"
+      puts "             Space Key: #{spacekey}"
+      return nil
+    else
+      return JSON.parse(res)['results'][0]['title'],
+             JSON.parse(res)['results'][0]['id'],
+             JSON.parse(res)['results'][0]['version']['number'],
+             JSON.parse(res)['results'][0]['status'],
+             JSON.parse(res)['results'][0]['history']['createdDate'],
+             JSON.parse(res)['results'][0]['history']['createdBy']['username'],
+             JSON.parse(res)['results'][0]['version']['when'],
+             JSON.parse(res)['results'][0]['_links']['webui']
+    end
+  end
+
+  def get_page_info_by_id(id, spacekey)
+    begin
+      res = RestClient.get "#{@@conf_url}/#{@@urn}/#{id}?os_username=#{@@login}&os_password=#{@@pwd}&expand=version,history"
+    rescue RestClient::ExceptionWithResponse => e
+      puts Nokogiri.XML(e.response)
+    end
+    # if res.nil? || JSON.parse(res)['results'].nil?
+    if res.nil?
+      puts "*** WARNING: Page not found for id: #{id}"
+      puts "             Space Key: #{spacekey}"
+      return nil
+    else
+      return JSON.parse(res)['title'],
+          JSON.parse(res)['id'],
+          JSON.parse(res)['version']['number'],
+          JSON.parse(res)['status'],
+          JSON.parse(res)['history']['createdDate'],
+          JSON.parse(res)['history']['createdBy']['username'],
+          JSON.parse(res)['version']['when'],
+          JSON.parse(res)['_links']['webui']
+    end
+  end
+
+end

data/lib/storage_format.rb

@@ -0,0 +1,117 @@
+class StorageFormat
+  attr_accessor :page_format
+
+  VALID_OPTIONS = [:type, :title, :spacekey, :content, :pageid, :parentid, :version]
+
+  def initialize(**options)
+    options.each do |key, value|
+      # puts "--> #{key} = #{value}"
+      raise "\n*** Error: unknown option #{key.inspect}\nValid option are:\n#{VALID_OPTIONS}" unless (VALID_OPTIONS.include?(key))
+
+      instance_variable_set("@#{key}", value)
+    end
+    @page_format = get_type_of_storage(@type)
+  end
+
+  def get_type_of_storage(type)
+    case type
+    when 'create_page_with_no_parent'
+      if [@title, @spacekey, @content].include?(nil)
+        puts "*** ERROR: Undefined parameter(s)\n    Inspection: #{self.inspect}"
+        exit(false)
+      else
+        %Q(
+        {
+          "type": "page",
+          "title": "#{@title}",
+          "space": {
+            "key": "#{@spacekey}"
+          },
+          "body": {
+            "storage": {
+              "value": "#{@content}",
+                "representation": "storage"
+            }
+          }
+        }
+        )
+      end
+    when 'create_page_with_parent'
+      if [@parentid, @title, @spacekey, @content].include?(nil)
+        puts "*** ERROR: Undefined parameter(s)\n    Inspection: #{self.inspect}"
+        exit(false)
+      else
+        %Q(
+        {
+            "type": "page",
+            "ancestors": [{"type":"page","id":"#{@parentid}"}],
+            "title": "#{@title}",
+            "space": {
+                "key": "#{@spacekey}"
+            },
+            "body": {
+                "storage": {
+                    "value": "#{@content}",
+                    "representation": "storage"
+                }
+            }
+        }
+        )
+      end
+    when 'update_page_with_no_parent'
+      if [@pageid, @title, @spacekey, @content, @version].include?(nil)
+        puts "*** ERROR: Undefined parameter(s)\n    Inspection: #{self.inspect}"
+        exit(false)
+      else
+        %Q(
+        {
+            "id":"#{@pageid}",
+            "type":"page",
+            "title":"#{@title}",
+            "space": {
+                "key":"#{@spacekey}"
+            },
+            "body": {
+                "storage": {
+                    "value":"#{@content}",
+                    "representation":"storage"
+                }
+            },
+            "version": {
+                "number":"#{@version}"
+            }
+        }
+        )
+      end
+    when 'update_page_with_parent'
+      if [@pageid, @parentid, @title, @spacekey, @content, @version].include?(nil)
+        puts "*** ERROR: Undefined parameter(s)\n    Inspection: #{self.inspect}"
+        exit(false)
+      else
+        %Q(
+        {
+            "id":"#{@pageid}",
+            "type":"page",
+            "ancestors": [{"type":"page","id":"#{@parentid}"}],
+            "title":"#{@title}",
+            "space": {
+                "key":"#{@spacekey}"
+            },
+            "body": {
+                "storage": {
+                    "value":"#{@content}",
+                    "representation":"storage"
+                }
+            },
+            "version": {
+                "number":"#{@version}"
+            }
+        }
+        )
+      end
+    else
+      puts "***ERROR: Wrong parameters for #{self.class.name}"
+      exit(false)
+    end
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: confluence-rest-api
+version: !ruby/object:Gem::Version
+  version: 1.0.6
+platform: ruby
+authors:
+- Gregory J. Miller
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-04-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- confluence-rest-api.gemspec
+- lib/confluence-rest-api.rb
+- lib/confluence.rb
+- lib/page.rb
+- lib/storage_format.rb
+homepage: https://github.com/grmi64/confluence-rest-api
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Ruby REST API Client to create, update, and view pages
+test_files: []