README.md
# Hatenablog
[](https://badge.fury.io/rb/hatenablog) [](https://github.com/kymmt90/hatenablog/actions?workflow=build)
[](https://codeclimate.com/github/kymmt90/hatenablog)
[](https://codeclimate.com/github/kymmt90/hatenablog/coverage)
> 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](http://developer.hatena.ne.jp/) 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`:
```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.
```yml
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](#factories).
### [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.
```yml
auth_type: basic
api_key: <%= ENV['API_KEY'] %>
user_id: <%= ENV['USER_ID'] %>
blog_id: <%= ENV['BLOG_ID'] %>
```
## Usage
```ruby
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.
```ruby
# 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.
```ruby
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
```ruby
client.title # Get the blog title
client.author_name # Get the blog author name
```
### Feeds
```ruby
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
```ruby
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
```ruby
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