re:CONNECT 2024 < Keynote Session 2 > やさしくつつみこむヨドバシ API
※本記事は、ブリスコラ主催「re:CONNECT 2024 ～つながりの再発見、そして新たな事業変革へ。」（2024年12月5日開催）での 株式会社ヨドバシリテイルデザイン サービスデプロイメント事業部 事業部長 戸田 宏司氏 氏 のKeynote Sessionをまとめたものです。本記事の最後に、講演内容全体をご覧いただける動画もご紹介しております。ぜひご視聴ください。
やさしくつつみこむヨドバシAPI
講演資料 こちらのリンクからご覧いただけます。（PDF）
株式会社ヨドバシリテイルデザイン
サービスデプロイメント事業部
事業部長
戸田 宏司氏
ヨドバシカメラのやさしいAPIとは
ヨドバシカメラでは、安心できる商品を確実・迅速にお客様 へ届けるために、信頼できる取引先および配送担当者・配送業者との円滑な連携が必要だと考えています。その手段として、業務ドメインごとに「優しさ」を重視した誰もが活用しやすい「Public API」を用意しているのだと戸田氏は説明します。
具体的には、API利用者がすぐに理解でき、都合に合わせてすぐに使えるREST APIを採用しており、戸田氏はRESTの提唱者であるRoy T. Fielding 氏の博士論文「Architectural Styles and the Design of Network-based Software Architectures」をなぞりながら、いくつもの「優しさ」を実装していることを紹介しました。
まず、Fielding氏の論文では利用者が利用だけに集中できるClient-Serverモデルを採用。その上で、文脈を持たずメッセージごとに完結するStatelessのシステムとしたため、複雑な手続きが不要で、メッセージを見れば内容が分かり、やり直しがいつでもできます。また、StatelessなのでCache ServerやProxy Serverを柔軟に設置でき、性能や安全性などの非機能要件を利用者側で考えられます。加えて、複雑なビジネスロジックを隠蔽できるLayeredにしました。これらが組み合わさることで、API利用者は業務について深く理解せずとも、メッセージのみで業務の依頼や情報取得ができるのです。
さらにインターフェースはHTTPとURI（Uniform Resource Identifier）ですので、Webに携わる技術者であれば誰もが知っているプロトコルを用いて、対象リソースを明確に指定し直感的に操作することができます。
一方で、ヨドバシカメラ内部ではAPI開発において「惑わない」を基本方針として、開発者が課題解決に集中できるように、多角的にサポートする環境を用意しています。惑うケースの1つに、URIで指し示すリソースを決める判断があります。例えば配送の場合、「荷物」は明らかにリソースですが、「配送伝票」はどうでしょうか。荷物の属性情報とする場合と、伝票そのものもリソースとする場合が考えられます。どちらでも設計・実装はできますが、配達業者が変更になる場合など伝票を貼り替えるケースがあることを踏まえれば、リソースとして扱ったほうが管理しやすいため適しています。しかし、この判断をエンジニアだけに委ねるのは負担を大きくしてしまいます。
「自由度が高いと開発者は迷子になりますし、エンジニアにとっては判断が難しい領域もあります。早めにステークホルダーを巻き込んで相談して方針を合意しなければ、顧客が本当に必要だったものを間違えたまま、時間とコストをかけて開発してしまうことになります。」（戸田氏）
やさしいAPIを惑わず開発するための3つの取り組み
50年以上にわたり世界のエンジニアが参考にしてきたミルト・ブライス氏のシステム開発方法論「PRIDE（PRofitable Information by DEsign）」においても、プロジェクトの各フェーズ担当者それぞれ自分の目線や都合で要件を捉えてしまうと「顧客が本当に必要だったもの」にならないことを示しています。これをVモデルで表現した場合、谷の深さと幅に置き換えて考えられそうです。
この考え方を踏まえると、お客様から聴き取った要件をそのまま実装できるオブジェクト指向で開発することでVモデルの谷を浅くすることができ、その要件をアジャイル環境でチームメンバーが自発的に造ってすぐにレビューできれば谷は狭くできる、すなわちギャップを小さくすることが可能になるのです。
しかしながら、誰もが全フェーズに対応できる能力を持っているわけではありません。そこでヨドバシカメラでは、3つの取り組みによって、一本道を迷うことなく突き進めるようにしています。
1.基本設計までは標準規約と開発設計ツールを利用
ヨドバシカメラでは、本来取り組むべき課題へ設計者が集中できるように、APIの標準規約を策定しています。これは一般的な標準規約になるよう、ブリスコラと協議を重ねて作り上げました。
この規約はブリスコラの開発設計ツールであるBAMs Designにも実装しており、APIの設計時にガイドしてくれるため、標準規約に違反していればアラートが表示されます。また、開発者ごとの同義語・類似語の揺れを解消するための辞書ツールも併せて活用しています。
2.「基本設計」以上、「詳細設計」未満のリソース定義はステークホルダーに付き合ってもらう
BAMs Designから生成されたOpenAPI Specは、API設計書公開サーバーであるBAMs Catalogで共有し、ステークホルダーがいつでも閲覧して判断できるようにしました。
3.詳細設計以降はヨドバシアーキテクチャを考慮したコードジェネレーターを使う
BAMs Designには、OpenAPI Specファイルからヨドバシアーキテクチャに最適化されたコードがジェネレーターの機能も内蔵されており、開発の生産性や品質向上に寄与しています。これもブリスコラと協力して作り上げました。
「このようにヨドバシカメラでは、自分たちの手で新しいサービスを世に送り出し、作ったAPIを公開することで利用者を介して新しいビジネスを創造できます。その興奮を共有できる仲間を募集しています。ぜひこちらのWEBサイトをご覧ください。」（戸田氏）
