多くのWebサービスが存在している今、新しいサービスを作る際には、すでに市場に存在しているサービスと連携することは必須要件といえます。
この理由としては、
- リソースの制約によって自社サービスで提供できる価値には限界があること
- そもそも、既存の業務ツールとシステムの連携をしていない限り、市場導入が困難であること
- 車輪の再発明を避け、技術投資の費用対効果を高めるため
といったものが考えられます。
連携の際には、連携先のシステムから使いやすいSDKが提供されていることもありますが、ニッチなドメインのサービスや、限られたパートナー企業にのみAPIを提供しているようなサービスでは、必ずしも扱いやすくはないAPIやドキュメントを頼りに連携を進める必要が生じます。
本記事では、異なるドメイン知識を有する他社のシステムと自システムを統合する際に、最初に割いておくべきコストについて自分の経験からまとめていきます。
システム連携に失敗すると何が起きるか？
まず、システム連携時に避けたい結果を明確にします。
システム連携の開始時には、連携の要件が明確になっていることが殆どでしょう。
その目的を達成できる手段を連携先のシステムから探し、自分のシステムからそのAPIを叩けるようにすることが、一旦のゴールになります。
これ以降のメンテナンスが不要な類の連携であれば、素朴な実装フローで問題が生じないこともあるでしょう。
しかし、ある程度複雑な連携であれば、将来的に以下のような問題が生じることが考えられます。
- 連携を行ったエンジニアに知識が閉じ込められてしまい、新しく連携を行う際に工数がかかる
- 異なるAPIを叩く必要が生じた際に、呼び出し元にロジックが散らばってしまっているため、既存資産を再利用できない
- 連携先のシステムのAPIが変更された時に、修正に初期実装と同様の工数を要する
連携失敗とはどのような状態か？
なぜ上記のような状況に陥りがちなのでしょうか？
その原因は、初期実装時の要件があまりにも明確すぎるから と言えるでしょう。
最近、続編が発売されましたが、オブジェクト指向UIデザインという本があります。
この本では、タスク指向UIと、オブジェクト指向UIという概念を使って、習熟しやすいUIデザインの方法を解説しています。
タスク指向UI / オブジェクト指向UI
本の内容を簡単に説明します。
アプリケーションを使っているユーザーの心理状態として以下のようなパターンが考えられます。
- 自分がアプリケーションを利用して実現したいタスクがはっきりとわかっている
- 自分がアプリケーションを利用して何ができるのかわかっていない
このうち、1のパターンでは、複雑な副作用を含む具体的なタスクを、すぐに実行できるようなUIが向いています。
例えば、毎日実行する、集計のバッチ処理を行うscriptを実行するためのボタンのようなものです。
2のパターンでは、ユーザー自身がアプリケーションの探索を通してできることを発見していけるようなUIが向いています。
具体的には、例えばメールクライアントのアプリを考えてみると、
トップページにはメールと人のアイコンの並びがあり、メールをクリックすると、
- 新着メール一覧
- メールを送信する
- メールを検索する
以上のようにメールのオブジェクトから連想されるようなタスクが表示されます。
人のアイコンをクリックすると、アドレス帳に登録しているユーザーの一覧があり、
さらにユーザーをクリックすると、過去のメールのやりとりが一覧されており
- 新規にメールを送信する
- アドレス帳から削除する
などなど、ユーザーにまつわる実行可能なタスクが表示されます。
タスク指向UIは、ドメインエキスパート向けのUIであり、特定の複雑なタスクを素早く実行するのに向いています。オブジェクト指向UIは、万人向けのUIであり、冗長ではあるが、誰もが使えるUIです。
コードで考えるとどうなるか？
さて、エンジニアにとってのUIはコードです。
理想的には、頻繁に使うコードはタスク指向UIで呼び出せるようにし、
あまり使わないコードはオブジェクト指向UIで呼び出せるようにしておきたいです。
しかし、エンジニアは、コードをUIとして扱うユーザーであると同時に、その実装者でもあります。
常に、実装をしているタイミングが、そのコードに関して最もフレッシュな知識を持っているタイミングになっています。
よく触られる部分のコードは、多くの人の目に触れることで、徐々にオブジェクト指向UIに近づいていくでしょうが、今回の記事の主題である、外部システムとの連携コードに関しては、ほとんど触られないために、タスク指向UIのまま放置されることが多いでしょう。
APIで取得されたデータは、ビジネスロジックの中で必要なプロパティだけが直接参照され、歯抜けの知識の状態で、将来の自分や、後任のエンジニアのモチベーションをこれでもかと下げることになります。
メンテナンス時の学習コストを下げる
エンジニアにとって、リリースを早めることは価値ですが、将来のリソースを節約を節約することも同時に価値です。後者の意識がなければ、開発に必要なリソースは無制限に膨らんでいくことになります。
一つ重要なのは、初期実装時にも呼び出すAPIのデータについての学習を行っているということです。
学習を行う過程で、ドキュメントを読み必要なプロパティのみを抜き出したはずです。Slackの分報やNotionなんかに書き散らしていたはずです。
学習した知識をコード上に残すこと、またはドキュメントから得た知識をコードとして表現することができれば、どれだけ将来の救いになることでしょう？
API連携時に必要なのは、APIのドメイン知識を学習した際の知識をコードとして残せる場所をあらかじめ作っておくこと です。
どのようにコードとして残すか？
APIはタスク指向のインターフェースです。
素朴に実装をすると、API呼び出しに主眼をおいたコードになってしまいがちです。
このようなコードでは、レスポンスのデータの解釈を呼び出し元に任せてしまうことを誘発してしまいがちです。
やることはシンプルです。
連携先のシステムとやり取りするデータに主眼を置き、呼び出すAPIレスポンスまたはリクエストをそれぞれ一つのドメインエンティティであると捉え、一つ一つデータ構造を分解、定義していきます。この分解したデータ構造は、知識を蓄積するための場所になります。
個人的には **「最初に本棚を作る」**と表現しています。
まとめ
意味のない面倒臭いことは、やるべきではないですが、
意味のある面倒臭いことは、意味を理解しなくては苦痛でしかなく雑になりがちです。
連携初期の面倒な作業がなんで必要なのかを社内共有するために記事にしました。
インテグレーションの機会が増えてきたので、社内のメンバーへの今後の面倒な気持ちが軽減すれば幸いです。
システム連携初期に割く学習コストを、将来の自分や後任のエンジニアが再度割くことを避けるために、最初に棚を作ってからドキュメントを読み込んでいくことをお勧めします。
Discussion