my_api_client 0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 ryz310
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.jp.md

@@ -0,0 +1,232 @@
+[![CircleCI](https://circleci.com/gh/ryz310/my_api_client.svg?style=svg)](https://circleci.com/gh/ryz310/my_api_client) [![Maintainability](https://api.codeclimate.com/v1/badges/861a2c8f168bbe995107/maintainability)](https://codeclimate.com/github/ryz310/my_api_client/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/861a2c8f168bbe995107/test_coverage)](https://codeclimate.com/github/ryz310/my_api_client/test_coverage)
+
+# MyApiClient
+
+MyApiClient は API リクエストクラスを作成するための汎用的な機能を提供します。Sawyer や Faraday をベースにエラーハンドリングの機能を強化した構造になっています。ただし、 Sawyer はダミーデータの作成が難しかったり、他の gem で競合することがよくあるので、将来的には依存しないように変更していくかもしれません。
+
+また、 Ruby on Rails で利用することを想定してますが、それ以外の環境でも動作するように作っているつもりです。不具合などあれば Issue ページからご報告下さい。
+
+## Installation
+
+この gem は macOS と Linux で作動します。まずは、my_api_client を Gemfile に追加します:
+
+```ruby
+gem 'my_api_client'
+```
+
+Ruby on Rails を利用している場合は `generator` 機能を利用できます。
+
+```sh
+$ rails g api_client path/to/resource https://example.com get_user:get:path/to/resource
+
+create  app/api_clients/application_api_client.rb
+create  app/api_clients/path/to/resource_api_client.rb
+invoke  rspec
+create    spec/api_clients/path/to/resource_api_client_spec.rb
+```
+
+## Usage
+
+### Basic
+
+最もシンプルな利用例を以下に示します。
+
+```rb
+class ExampleApiClient < MyApiClient::Base
+  endpoint 'https://example.com'
+
+  attr_reader :access_token
+
+  def initialize(access_token:)
+    @access_token = access_token
+  end
+
+  # GET https://example.com/users
+  #
+  # @return [Sawyer::Response] HTTP response parameter
+  def get_users
+    get 'users', headers: headers, query: { key: 'value' }
+  end
+
+  # POST https://example.com/users
+  #
+  # @param name [String] Username which want to create
+  # @return [Sawyer::Response] HTTP response parameter
+  def post_user(name:)
+    post 'users', headers: headers, body: { name: name }
+  end
+
+  private
+
+  def headers
+    {
+      'Content-Type': 'application/json;charset=UTF-8',
+      'Authorization': "Bearer #{access_token}",
+    }
+  end
+end
+
+api_clinet = ExampleApiClient.new(access_token: 'access_token')
+api_clinet.get_users #=> #<Sawyer::Response>
+```
+
+クラス定義の最初に記述される `endpoint` にはリクエスト対象のスキーマとホストを定義します。ここにパス名を含めても反映されませんのでご注意ください。
+次に、 `#initialize` を定義します。上記の例のように Access Token や API Key などを設定することを想定します。必要なければ定義の省略も可能です。
+続いて、 `#get_users` や `#post_user` を定義します。メソッド名には API のタイトルを付けると良いと思います。メソッド内部で `#get` や `#post` を呼び出していますが、これがリクエスト時の HTTP Method になります。他にも `#patch` `#put` `#delete` が利用可能です。
+
+### Error handling
+
+上記のコードにエラーハンドリングを追加してみます。
+
+```rb
+class ExampleApiClient < MyApiClient::Base
+  endpoint 'https://example.com'
+
+  error_handling status_code: 400..499, raise: MyApiClient::ClientError
+
+  error_handling status_code: 500..599 do |params, logger|
+    logger.warn 'Server error occurred.'
+    raise MyApiClient::ServerError, params
+  end
+
+  error_handling json: { '$.errors.code': 10..19 }, with: :my_error_handling
+
+  # Omission...
+
+  private
+
+  # @param params [MyApiClient::Params::Params] HTTP req and res params
+  # @param logger [MyApiClient::Logger] Logger for a request processing
+  def my_error_handling(params, logger)
+    logger.warn "Response Body: #{params.response.body.inspect}"
+    raise MyApiClient::ClientError, params
+  end
+end
+```
+
+一つずつ解説していきます。まず、以下のように `status_code` を指定するものについて。
+
+```rb
+error_handling status_code: 400..499, raise: MyApiClient::ClientError
+```
+
+これは `ExampleApiClient` からのリクエスト全てにおいて、レスポンスのステータスコードが `400..499` であった場合に `MyApiClient::ClientError` が例外として発生するようになります。 `ExampleApiClient` を継承したクラスにもエラーハンドリングは適用されます。ステータスコードのエラーハンドリングは親クラスで定義すると良いと思います。
+
+なお、 `status_code` には `Integer` `Range` `Regexp` が指定可能です。`raise` には `MyApiClient::Error` を継承したクラスが指定可能です。`my_api_client` で標準で定義しているエラークラスについては以下のソースコードをご確認下さい。
+
+https://github.com/ryz310/my_api_client/blob/master/lib/my_api_client/errors.rb
+
+次に、 `raise` の代わりに Block を指定する場合について。
+
+```rb
+error_handling status_code: 500..599 do |params, logger|
+  logger.warn 'Server error occurred.'
+  raise MyApiClient::ServerError, params
+end
+```
+
+上記の例であれば、ステータスコードが `500..599` の場合に Block の内容が実行れます。引数の `params` にはリクエスト情報とレスポンス情報が含まれています。`logger` はログ出力用インスタンスですが、このインスタンスを使ってログ出力すると、以下のようにリクエスト情報がログ出力に含まれるようになり、デバッグの際に便利です。
+
+```text
+API request `GET https://example.com/path/to/resouce`: "Server error occurred."
+```
+
+リクエストに失敗した場合は例外処理を実行する、という設計が一般的だと思われるので、基本的にブロックの最後に `raise` を実行する事になると思います。
+
+最後に `json` と `with` を利用する場合について。
+
+```rb
+error_handling json: { '$.errors.code': 10..19 }, with: :my_error_handling
+```
+
+`json` には `Hash` の Key に [JSONPath](https://goessner.net/articles/JsonPath/) を指定して、レスポンス JSON から任意の値を取得し、 Value とマッチするかどうかでエラーハンドリングできます。Value には `String` `Integer` `Range` `Regexp` が指定可能です。上記の場合であれば、以下のような JSON にマッチします。
+
+```json
+{
+    "erros": {
+        "code": 10,
+        "message": "Some error has occurred."
+    }
+}
+```
+
+`with` にはインスタンスメソッド名を指定することで、エラーを検出した際に任意のメソッドを実行させることができます。メソッドに渡される引数は Block 定義の場合と同じく `params` と `logger` です。
+
+```rb
+# @param params [MyApiClient::Params::Params] HTTP req and res params
+# @param logger [MyApiClient::Logger] Logger for a request processing
+def my_error_handling(params, logger)
+  logger.warn "Response Body: #{params.response.body.inspect}"
+  raise MyApiClient::ClientError, params
+end
+```
+
+### Retry
+
+WIP
+
+#### MyApiClient::NetworkError
+
+WIP
+
+### One request for one class
+
+多くの場合、同一ホストの API は リクエストヘッダーやエラー情報が同じ構造になっているため、上記のように一つのクラス内に複数の API を定義する設計が理にかなっていますが、 API 毎に個別に定義したい場合は、以下のように 1 つのクラスに 1 の API という構造で設計することも可能です。
+
+```rb
+class ExampleApiClient < MyApiClient::Base
+  endpoint 'https://example.com'
+
+  error_handling status_code: 400..599
+
+  attr_reader :access_token
+
+  def initialize(access_token:)
+    @access_token = access_token
+  end
+
+  private
+
+  def headers
+    {
+      'Content-Type': 'application/json;charset=UTF-8',
+      'Authorization': "Bearer #{access_token}",
+    }
+  end
+end
+
+class GetUsersApiClient < ExampleApiClient
+  error_handling json: { '$.errors.code': 10 }, raise: MyApiClient::ClientError
+
+  # GET https://example.com/users
+  #
+  # @return [Sawyer::Response] HTTP response parameter
+  def request
+    get 'users', query: { key: 'value' }, headers: headers
+  end
+end
+
+class PostUserApiClient < ExampleApiClient
+  error_handling json: { '$.errors.code': 10 }, raise: MyApiClient::ApiLimitError
+
+  # POST https://example.com/users
+  #
+  # @param name [String] Username which want to create
+  # @return [Sawyer::Response] HTTP response parameter
+  def request(name:)
+    post 'users', headers: headers, body: { name: name }
+  end
+end
+```
+
+### Timeout
+
+WIP
+
+### Logger
+
+WIP
+
+## Contributing
+
+不具合の報告や Pull Request を歓迎しています。OSS という事で自分はなるべく頑張って英語を使うようにしていますが、日本語での報告でも大丈夫です :+1:

data/README.md

@@ -0,0 +1,45 @@
+[![CircleCI](https://circleci.com/gh/ryz310/my_api_client.svg?style=svg)](https://circleci.com/gh/ryz310/my_api_client) [![Maintainability](https://api.codeclimate.com/v1/badges/861a2c8f168bbe995107/maintainability)](https://codeclimate.com/github/ryz310/my_api_client/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/861a2c8f168bbe995107/test_coverage)](https://codeclimate.com/github/ryz310/my_api_client/test_coverage)
+
+# MyApiClient
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/my_api_client`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'my_api_client'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install my_api_client
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/my_api_client. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the MyApiClient project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/my_api_client/blob/master/CODE_OF_CONDUCT.md).

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/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'my_api_client'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/release

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# usage: bin/release VERSION
+
+require 'bundler/setup'
+require 'pr_comet'
+
+VERSION_FORMAT = /\A\d+\.\d+\.\d+(\.(pre|beta|rc)\d?)?\z/.freeze
+version = ARGV[0]
+pr_comet = PrComet.new(base: 'master', branch: "update/v#{version}")
+
+# Verifying
+abort 'usage: bin/release VERSION' if version.nil?
+abort 'A version must be like a `1.2.3`' unless version =~ VERSION_FORMAT
+
+# Modify a version file
+pr_comet.commit ':comet: Update version' do
+  File.write('lib/my_api_client/version.rb', <<~VERSION)
+    # frozen_string_literal: true
+
+    module MyApiClient
+      VERSION = '#{version}'
+    end
+  VERSION
+end
+
+# Bundle Update
+pr_comet.commit ':comet: Run $ bundle update' do
+  `bundle update`
+end
+
+# Create a pull request
+pr_comet.create!(title: "Update v#{version}", body: '')

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/generators/rails/USAGE

@@ -0,0 +1,11 @@
+Description:
+    Generate a new api client class files.
+
+Example:
+    `rails g api_client path/to/resource https://example.com get_user:get:path/to/resource`
+
+    This will create:
+        create  app/api_clients/application_api_client.rb
+        create  app/api_clients/path/to/resource_api_client.rb
+        invoke  rspec
+        create    spec/api_clients/path/to/resource_api_client_spec.rb

data/lib/generators/rails/api_client_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Rails
+  # rails g api_client
+  class ApiClientGenerator < Rails::Generators::NamedBase
+    source_root File.expand_path('templates', __dir__)
+    check_class_collision suffix: 'ApiClient'
+
+    argument :endpoint,
+             type: :string,
+             default: 'https://example.com',
+             banner: '{schema and hostname}'
+    argument :requests,
+             type: :array,
+             default: %w[get_resource:get:path/to/resource post_resource:post:path/to/resource],
+             banner: '{action}:{method}:{path} {action}:{method}:{path}'
+
+    def generate_root_class
+      file_path = File.join('app/api_clients', 'application_api_client.rb')
+      return if File.exist?(file_path)
+
+      template 'application_api_client.rb.erb', file_path
+    end
+
+    def generate_api_client
+      file_path = File.join('app/api_clients', "#{route_url.singularize}_api_client.rb")
+      template 'api_client.rb.erb', file_path
+    end
+
+    hook_for :test_framework
+  end
+end

data/lib/generators/rails/templates/api_client.rb.erb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class <%= "#{class_name}ApiClient" %> < ::ApplicationApiClient
+  endpoint '<%= endpoint %>'
+
+  # error_handling json: { '$.errors.code': 10 } do |params, logger|
+  #   # Behavior when detected an error.
+  # end
+
+  def initialize
+  end
+
+<% requests.each do |request| -%>
+<% action, http_method, pathname = request.sepalate(':') -%>
+  # <%= "#{http_method.upcase} #{endpoint}/#{pathname}" %>
+  #
+  # @return [Sawyer::Resource] Description of the API response
+  # @raise [MyApiClient::Error] Description of the error
+  # @see Reference of the API
+  def <%= action %>
+<% if http_method == 'get' -%>
+    query = {}
+    <%= http_method %> '<%= path %>', query: query, headers: headers
+<% else -%>
+    body = {}
+    <%= http_method %> '<%= path %>', body: body, headers: headers
+<% end -%>
+  end
+<% end -%>
+
+  private
+
+  def headers
+    {
+      'Content-Type': 'application/json',
+    }
+  end
+end