Hatenablog

A library for Hatena Blog AtomPub API

This gem supports following operations through OAuth 1.0a or Basic authentication:

• Get blog feeds, entries and categories
• Post blog entries
• Update blog entries
• Delete blog entries

Installation

Install the gem

Add this line to your application's Gemfile:

gem 'hatenablog'

And then execute:

$ bundle

Or install it yourself as:

$ gem install hatenablog

Get OAuth credentials

You need to set up OAuth 1.0a keys and tokens before using this gem.

1. Get consumer key and consumer key secret

Access Hatena application registoration page and get your application consumer key.

2. Get your access token and access token secret

Execute this command:

$ get_hatena_oauth_access_token <your consumer key> <your consumer secret>
Visit this website and get the PIN: https://www.hatena.com/oauth/authorize?oauth_token=XXXXXXXXXXXXXXXXXXXX
Enter the PIN: <your PIN> [Enter]
Access token: <your access token>
Access token secret: <your access token secret>

3. [Optional] Set up the YAML configuration file

The default configuration file name is config.yml:

consumer_key: <Hatena application consumer key>
consumer_secret: <Hatena application consumer secret>
access_token: <Hatena application access token>
access_token_secret: <Hatena application access token secret>
user_id: <Hatena user ID>
blog_id: <Hatenablog ID>

This file accepts ERB syntax.

consumer_key: <%= ENV['CONSUMER_KEY'] %>
consumer_secret: <%= ENV['CONSUMER_SECRET'] %>
access_token: <%= ENV['ACCESS_TOKEN'] %>
access_token_secret: <%= ENV['ACCESS_TOKEN_SECRET'] %>
user_id: <%= ENV['USER_ID'] %>
blog_id: <%= ENV['BLOG_ID'] %>

blog_id means your Hatena Blog domain, like "example-user.hatenablog.com".

You also can set these configurations in your code as described in the below section.

[Optional] Get Basic authentication credentials

If you want to use Basic authentication, visit http://blog.hatena.ne.jp/#{user_id}/#{blog_id}/config/detail and check your API key and set up config.yml like the following.

auth_type: basic
api_key: <%= ENV['API_KEY'] %>
user_id: <%= ENV['USER_ID'] %>
blog_id: <%= ENV['BLOG_ID'] %>

Usage

require 'hatenablog'

# Read the configuration from 'config.yml'
Hatenablog::Client.create do |blog|
  # Get each entry's content
  blog.entries.each do |entry|
    puts entry.content
  end

  # Post new entry
  posted_entry = blog.post_entry(
    'Entry Title',
    'This is entry contents', # markdown form
    ['Test', 'Programming']   # categories
  )

  # Update entry
  updated_entry = blog.update_entry(
    posted_entry.id,
    'Revised Entry Title',
    posted_entry.content,
    posted_entry.categories
  )

  # Delete entry
  blog.delete_entry(updated_entry.id)
end

API

Factories

You can create the client from the configuration file.

# Create the client from "./config.yml"
client = Hatenablog::Client.create

# Create the client from the specified configuration
client = Hatenablog::Client.create('../another_config.yml')

Hatenablog::Client.create do |client|
  # Use the client in the block
end

You can also create the client with a block for configurations.

client = Hatenablog::Client.new do |config|
  config.consumer_key        = 'XXXXXXXXXXXXXXXXXXXX'
  config.consumer_secret     = 'XXXXXXXXXXXXXXXXXXXX'
  config.access_token        = 'XXXXXXXXXXXXXXXXXXXX'
  config.access_token_secret = 'XXXXXXXXXXXXXXXXXXXX'
  config.user_id             = 'example-user'
  config.blog_id             = 'example-user.hatenablog.com'
end

Blog

client.title       # Get the blog title
client.author_name # Get the blog author name

Feeds

feed = client.next_feed # Get the first feed when no argument is passed
feed.uri
feed.next_uri    # The next feed URI
feed.title
feed.author_name
feed.updated     # Updated datetime

feed.entries # entries in the feed
feed.each_entry do |entry|
  # ...
end
feed.has_next? # true if the next page exists
next_feed = client.next_feed(feed)

Entries

client.get_entry('0000000000000000000') # Get the entry specifed by its ID
client.entries     # Get blog entries in the first page
client.entries(1)  # Get blog entries in the first and the second page
client.all_entries # Get all entries in the blog

entry = client.post_entry(
  'Example Title',                  # title
  'This is the **example** entry.', # content
  ['Ruby', 'Rails'],                # categories
  'yes',                            # draft
  '2022-04-11T15:43:20+09:00'       # updated
)
entry.id
entry.uri
entry.edit_uri
entry.author_name
entry.title             #=> 'Example Title'
entry.content           #=> 'This is the **example** entry.'
entry.formatted_content #=> '<p>This is the <strong>example</strong> entry.</p>'
entry.draft             #=> 'yes'
entry.draft?            #=> true
entry.categories        #=> ['Ruby', 'Rails']
entry.updated           # Updated datetime

client.update_entry(
  entry.id,
  entry.title,
  'This is the **modified** example entry.',
  entry.categories,
  'no'
)
client.delete_entry(entry.id)

Categories

categories = client.categories # Get categories registered in the blog
categories.each do |cat|
  puts cat
end

# When categories are fixed, you can only use those categories for your entries.
# ref: https://tools.ietf.org/html/rfc5023#section-7.2.1.1
categories.fixed?

Contributing

1. Create your feature branch (git checkout -b my-new-feature)
2. Commit your changes (git commit -am 'Add some feature')
3. Push to the branch (git push origin my-new-feature)
4. Create a new Pull Request

License

MIT