WebAPIの設計に力を入れよう

LITALICOの主にバックエンド側を担当しているエンジニア、@t-kontaです。
この記事は『LITALICO Advent Calendar 2020』8日目の記事です。

はじめに

LITALICOでは福祉サービスに関連する請求業務を簡単に行えるよう支援するサービスを提供しています。障害福祉サービス等の報酬改定は原則3年に一度行われますので、システムもそれらに追随していく必要があります。

その為、当初から変化に強く、柔軟に壊しやすくという標語をあげてシステム開発に挑んできました。マイクロサービス的な構成を取り入れたものその一環です。

さて、来年度の法改正に伴う全容も見え始め、開発ではその予測と対策にてんやわんやな状況が続いています。報酬に関する計算が異なる為、年度ごとに処理を分ける必要があるのですが、WebAPIのエンドポイントをどのように扱うかといった議論もされました。

振り返ると、WebAPIの設計については注意を割くリソースが少し不足していたかもしれません。
そこで、WebAPIの設計を考える上でどうあるべきだったかという反省を踏まえて、設計で大切にしたいことを記しておこうと思います。

WebAPI設計はアプリケーションの一部

ところでAPIとは何でしょう。
Application Programming Interface の略語だったりします。

自分は普段「IFさえ問題なければ何とかなる」という発言をたまにしますし、その辺りがどうなっているかという点に敏感です。コードレビューをする際に様々な観点はあると思いますが、そのオブジェクトがどのようなIFを持っているかを一番気にします。それさえ問題なければ中のコードがどんなに汚くても構まわないとすら思っています（最終的には一定の品質を期待します）。

なぜIFが大事かといえば、それが一度公開され場合に容易に変更が出来なくなるものだからです（¹）。内部的な変更は影響を局所化出来ますが、公開され利用され始めたAPIの変更は大きなコストを伴うものになってしまいます。

WebAPI、頭にWebとついており何となくプログラムを実行する為にアクセスするURI、ぐらいの印象があるかもしれません。しかし、APIである以上これはれっきとしたアプリケーションのIFなのです。

WebAPIをただの玄関として捉えてしまったイメージ

しかし本来はWebAPIの設計を含めて一つのアプリケーション

さらに発展させたイメージ

web系のシステム開発では、APIのエンドポイントがどうあるべきかという議論が後回しになってしまう事が経験上多くありました。特に単体としては注意深く見ても、全体を俯瞰しての相互の影響、バランスを見るという観点が抜けてしまいがちな気がしています。

API一覧を眺めてみることの重要性

API一覧がありそれを眺めていると、そのシステムにどのようなユースケースがあるのかをイメージ出来ます。さらにはそのシステムがどのような価値を提供しようとしてるのかも見えてきます。

自分が所属する開発部では、SwaggerやapiDocといったドキュメント生成ツールを活用しています。これらのツールは個別のAPIを詳細に見るにはとても優れているのですが、一覧性がやや悪いように思えます。

ドキュメント生成ツールを使用しつつ、それらから以下のように全体を一覧出来る仕組みを整えるとよいかもしれません。

method	endpoint	目的
GET	http://xxx/children	児童一覧を取得する
GET	http://xxx/children/{code}	児童を取得する
POST	http://xxx/children	児童を登録する
PUT	http://xxx/children/{code}	児童を編集する

こうすることで、あるAPIがバランスを欠いてないか、目的が重複していないかといったチェックが出来るようになります。

特にREST APIを意識して開発する場合、endpointにリソースの情報が適切に表され、methodと対応して目的に合致しているかを見ます。なお、URI中のクエリーパラメーターは原則省略可能なものであり、それらが無くともmethodとendpointのみでAPIの性質が伝わるようにする必要があります。

おわりに

とりあえず、API一覧とコール回数眺めていると何か楽しいです。
別の機会にもっと具体的な事例に踏み込めればと思います。

明日は @katzumi さんの記事です。
お楽しみに！

1. ここでいう公開とは、ネット上での公開非公開ということではなく、自分以外の開発者やユーザーに認知され利用され始める状況を指しています。 ↩