github_web_api

github_web_api (Kotlin モジュール)

GitHub REST API とHTTP 通信をするモジュール。

使い方

利用側で準備すること

• OkHttpClient のインスタンス
  • OkHttpClient のAPI ドキュメント に OkHttpClients Should Be Shared とあるため
• 通信キャッシュの保存先のディレクトリ
  • OkHttp のデフォルトではOFF ですが、HTTP Status Code 304 の記述があり、アプリ側でキャッシュの考慮が必要なため

実装の流れ

1. インスタンスを生成する

   val githubWebApi = GitHubWebApi(
       applicationId = "",
       cacheDir = applicationContext.cacheDir,
       client = okhttpClient,
   )

2. プロパティendpoint 経由で通信を実行する (※Kotlin Coroutines のScope が必要)
   • 例) リポジトリ検索

     try {
         val response = githubWebApi.endpoint.getSearchRepositories("android")
     } catch (e: IOException) {
         // 端末オフラインや通信タイムアウトなど
     } catch (e: Exception) {
         // 想定外のエラー
         // TODO: クラッシュ分析ツールへ連携
     }

注意事項

• GitHub REST API からエラーが返ってきた場合は、クラッシュ分析ツールへ連携することを推奨します
  • REST API を使用するためのベスト プラクティス - GitHub Docs の記載で、意図的に無視すると不正利用と見なされる場合がありそうなため
• 通信キャッシュ用の領域は4MB に設定されています
• 通信タイムアウトは10.5 秒に設定されています
• もしProguard が必要な場合は、利用側で調整してください

開発メモ

• GitHub REST API の仕様が変わった場合、本モジュールも追従します
• Kotlin Explicit API モードがstrict レベルで有効となっています
• OpenAPI 定義 から生成したコードを、編集した上で流用しています
  • IDE の検索機能で、([a-z])([A-Z]) を$1_\l$2 で置換し、変数名をsnake case 化
    • Moshi はsnake case をcamel case へ自動変換する機能が無いのでJSON キー名と揃えるため (※関連stack overflow)
    • 本モジュールは外部サービスに強く依存し、アプリで利用するうえで信用できるか不明のため、その注意喚起を含め違和感を持ってもらうため、snake case のままとしています
  • Moshi の設定追加
    • Android モジュールでminify をかけても大丈夫なように調整
  • 型の前についているkotlin. を削除
  • 型変更
    • Array -> List
    • BigDecimal -> Int
    • nullable
      • 必須のものはnullable 化
      • 任意なものはnullable + 既定値null を割り当て
  • コメントの整形
• エンドポイントに紐づくメソッド名は、HTTP 動詞 + パス というふうに付けています
• ユニットテスト用のサンプルデータは test/resources/ にあるJSON ファイルを書き換えることで変更可能です

関連リンク

GitHub REST API

• エンドポイント
  • https://docs.github.com/ja/rest/search/search?apiVersion=2022-11-28#search-repositories
• メタ情報
  • API のバージョン - GitHub Docs
  • REST API のリソース - GitHub Docs
    • Timeouts
    • User agent の必要性
    • クライアントエラー
  • メディアの種類 - GitHub Docs

依存ライブラリ (build.gradle)

• コア
  • OkHttp BOM (Maven Central)
    • OkHttp
• モジュール内部利用
  • Moshi Adapters (Maven Central)
  • Moshi Codegen (Maven Central)
  • Retrofit (Maven Central)
  • Retrofit Converters
    • Converter: Moshi (Maven Central)
• テスト
  • JUnit4 (Maven Central)
  • Kotlin Coroutines BOM (Maven Central)
    • Kotlin Coroutines Test
  • OkHttp BOM
    • OkHttp MockWebServer
  • (Okio)