この記事はAutify Advent Calendar 202115日目です。
AutifyのWeb API用のクライアントライブラリを作成したの少しまとめます。
https://github.com/trknhr/autify-go
Autifyとは
自動E2Eテスト支援ツールです。私の所属している会社で採用されているため私も業務の時間で触ることが多いです。
このライブラリはなにをするか
Autify Web APIを直接叩く部分をラップします。ユーザーにとってはGoでAPIを呼び出してそのデータを取得するのではなく関数を呼ぶだけで該当のAPIを操作できることになります。
https://autifyhq.github.io/autify-api/#/schedule/post_schedules__schedule_id_
なぜ作ったか
Autifyのシナリオの中身まで検索したい時がありその時に即興でWeb APIのラッパー的なのを作っていたのでそれをライブラリとして切り出しました。
苦労した点
レスポンスのデータの型がswaggerの記載と違う
大体合ってる気がしましたが、レスポンスのJSONのデータとswaggerに記載されている型と異なることがあり1つづつAPIのレスポンスを確認する必要がありました。
特に欲しかったシナリオの中身のステップを取得する箇所はswaggerファイルではごっそり抜けてたので1つ1つデータを確認する必要がありました。
迷った点
int or int64?
Goのintは処理系によってint32 or int64になります。IDはかなり大きな値もあり得ると21億より多くなるかも判断して当初からIDを全てint64に統一しています。
しかしGoに強い人に聞いたところ大体いまのPCの処理系は64bitだからあんまり気にする必要ないんじゃないかという助言を受け、intにしておいた方がよかったと感じました。int64は使う方もint64であることを意識せざる場面があるからです。
例えばfunc hoge(id int64) {}という関数は
hoge(1) // OK
id := 1
hoge(id) //NG
となりユーザがint64を意識する必要がありイマイチだなぁと感じました。
APIのバージョニングをどうするか
大抵のREST APIでバージョンニングがされています。バージョンニングに対してどうやってライブラリと対応するべきかという点についても調べました。結論から言うと今回のライブラリは何も考えずに作成しています。
バージョンニングされたディレクトリを作成するパターン
/v1/*.go
/v2/*.go
のようなディレクトリを作成して、ユーザー側で欲しいバージョンのWeb APIクライアントを
github.com/hogehoge/v1
のようにインポートする必要があります。
ライブラリは特定のバージョンのみを対応するパターン
これは何も考えず現在のライブラリは特定のバージョンのみをサポートすると言う考え方です。Web APIのバージョンが上がったらリポジトリを新たに作るか、新しいバージョンのWeb APIに適応するようにライブラリをアップグレードします。
クエリパラメーター
クエリパラメーターをどうやて組み立てるかについて少し悩みました。当初は以下のように直感的に実装しました。
var (
page *int
id *int
)
if page != nil {
//etc
}
この方法でも悪くないのですが、if文を何回も書くのが手間なところとベタガキなので使い回しの効きにくいことがネックでした。
mapにしてfor分で回すことも考えました。
クエリパラメータのためにmapを作成するのも少し嫌でしたしkeyとなる文字列はやはり使い回しのききにくいものとなっていました。
と色々調べて回った結果クエリパラメータをセットする関数を返す関数を作成する方法を採用しました。クエリパラメータの種類ごとに関数を作成する必要がありますが、これなら使い回しがしやすく且つ使う方も直感的に使えそうでした。
実装はこの辺を参照ください
https://github.com/trknhr/autify-go/blob/main/request_param.go
まとめ
Web APIのクライアントは処理としてはかなり単純でGoのライブラリ作成の練習になりました。普段ライブラリの作成などを行わないのでとても勉強になりました。限られた工数の中で作成したライブラリなのでユニットテストなどまだまだやりたい部分は残りますが、徐々に良い形にして行けたらと思います。