「つくる人」と「つかう人」のこだわりを追求する

tsumug edge

OpenAPIとSwagger:TiNKのテクノロジー

株式会社tsumug(ツムグ)の「TiNK(ティンク)」シリーズにはさまざまな技術が使われていますが、ここではその中で使われている技術について、紹介します。第4回は「OpenAPI」と「Swagger」です。


【TiNK】#もう許してあげない編 キーシェアリング機能

鍵を安全に開け閉めするために、株式会社tsumugが開発、提供しているコネクティッド・ロック「TiNK(ティンク)」には、さまざまな技術が使われています。
今回は、クライアントとサーバー間でのやりとりを定める「OpenAPI」という規格、そして、それをサポートするツールである「Swagger(スワッガー)」について紹介します。

ネットを使ったシステムの構成

スマホやパソコンを使って操作するシステムのほとんどは、①操作する側のスマホやパソコン上で動作するプログラム、②サーバー上で動作するプログラムーーの2つから構成されています。

TiNKも例外ではありません。
TiNKでは、スマホやパソコンから操作して、新しい鍵を発行したり、鍵を失効させたり、また、誰がいつ鍵を開けたのかという記録を確認したりできますが、こうした操作は、スマホやパソコンからサーバーに向けて指示を出し、その後サーバー上のプログラムが実行され、その処理結果が返される、という動作をしています。

ところで、操作する側の装置ですが、いちいち、「スマホやパソコン」と記述するのは煩雑ですし、そもそも、それ以外の装置で操作することもあります。
そこで以下では、こうしたユーザーが操作する端末の総称として「クライアント」と呼ぶことにします。

f:id:sofkun:20180821165134p:plain
クライアントとサーバーの関係

ユーザーの操作を待ち受けるAPI

さて、サーバー側のプログラムは、クライアントに対して機能を提供するのが目的です。TiNKの場合、具体的には、「新しい鍵を発行する」「鍵を失効する」「鍵の利用履歴を見る」などです。

サーバー側のプログラムは、こうした機能ごとに処理を分けて、「どのような手順で実行すれば、何が実行され、結果がどうなるのか」を定義しておきます。このような実行手順規則のことを「API (Application Programming Interface)」と言います。

TiNKのようなシステムでは、誰でもAPIを実行できるのはセキュリティ上問題があるので、正しいユーザーかどうかを認証する仕組みもAPIとして定め、正しく認証しない場合は使えないようにするといったことも取り決めます。

クライアントは、こうしたAPIの取り決めに従ってサーバーのプログラムを実行することで、さまざまな機能を実行します。

APIは機能単位なので、図からわかるように、その数は、とてもたくさんあります。クライアントのプログラムは、こうしたAPIを1つ1つ実行するのではなく、複数組み合わせて実行することで、ユーザーが望む機能の操作に対応します。

f:id:sofkun:20180821165213p:plain
APIの仕組み

規則さえ合わせれば、他のクライアントでも操作できる

サーバー側をAPI化するもっとも大きなメリットは、定めたAPIの実行手順に則ってさえいれば、クライアントの種類を制限しないという点です。

たとえば、TiNKではまだ提供されていませんが、将来、専用のPCアプリやIoTデバイス、もしくはAIスピーカーのような他の装置から操作できるようにする予定です。

このような「どんなクライアントからでも、手順に則りさえすれば、同じように操作できる」というようのが、サーバー側にプログラムを置き、それをAPIとして定めたシステムを作る大きなメリットです。

f:id:sofkun:20180821165307p:plain
手順に則っていればどんなクラインとでも大丈夫

API定義の苦悩

このようにAPIはクライアントとサーバーがやりとりするのに不可欠、かつシステムの拡張性を高める仕組みではありますが、実は、作るのには多くの工数がかかります。

ほとんどのシステムでは、「APIを提供するサーバーアプリケーション開発者」と「クライアントのアプリケーションを作る開発者」は異なります。一人で担当することも不可能ではありませんが、両方担当すると、仕事量が劇的に増えますし、そもそも、それぞれの開発に得手不得手もあります。

分担して開発する場合、サーバーに置くAPIを作る開発者は、「どのような手順で、どのようなデータを送信すると、どのようになるのか」をきちんと定めて、それをクライアントアプリケーションの開発者に伝えなければなりません。 また、クライアントアプリケーションの開発者は、その手順通りにプログラムを作ってサーバーと通信するプログラムを作らなければなりません。

そして、こうしたAPIの仕様書のようなドキュメントを書くことも大変ですし、記入漏れが誤解が生じるような書き方があるとプログラムの作り直しにもつながるので、細心の注意をしなければなりません。これは結構な労力です。

そこで必要とされるのが、APIの仕様を、誰が書いても同じように作れるようにする標準化です。標準化すれば記入漏れや誤解が生じる可能性が少なくなります。そして自動化ツールを使うことで、さらに人間が見やすいドキュメントに整形したり、そのAPI仕様のプログラムを実行するためのプログラムのひな形を作ったりすることもできるようになります。

f:id:sofkun:20180821165343p:plain
APIの仕様をつくる必要がある

API仕様を標準化するOpen API

こうした標準化の方法として、さまざまな規格が提唱されていますが、最近、よく使われるのが、Open API Initiative(https://www.openapis.org/)という団体によって提唱されている「Open API」です。Open API Initiativeには、マイクロソフトやGoogle、IBMなどの業界を代表する企業も参加しており、業界標準となりつつあります。

Open APIでは、「YAML(ヤムル)」という書式で、サーバー側のAPI規則を書きます。この書式は厳格に文法が定まっており、機械的に処理可能な書式です。ドキュメントとして記述するのと違って、曖昧さが入り込む余地がありません。

ドキュメントやプログラムのひな形が作れるSwagger

そしてOpen APIには、Open APIの仕様に則ったYAMLファイルを作成するツール、そのYAMLファイルから人間が見やすいドキュメントを作ったり、そのYAMLファイルに記された仕様の通りに動くサーバー側やクライアント側で動くプログラムのひな形を作ったりするツールが提供されています。それが、「Swagger」です。

TiNKでは、Swaggerを使ってYAMLファイルからドキュメントやプログラムを自動生成することで、開発を効率化しています。

f:id:sofkun:20180821165423p:plain
Swaggerで自動化を進める

実は、クライアント側のプログラムもサーバー側のプログラムも、「ネットワークを介した通信」という処理が存在するので、YAMLで書かれたファイルに準じて動くプログラムをイチからすべてを記述すると、開発者の負担が大きいのです。
こうした処理の生成を自動化できれば、開発者の負担を大きく軽減できます。

TiNKでは、実際、クライアント側のプログラムの作成に、こうした自動生成されたプログラムを使うことで、工期を大きく短縮しています。自動生成されたプログラムの部分は人間が介入しないため、プログラマが作るのに比べて不具合が含まれる可能性がとても少なくなります。その結果、完成したプログラムの品質も良くなります。

APIを公開すれば、みんなが使える

Open APIはAPIを記述する標準的な記法なので、さまざまなクライアントをつなげやすいという利点があります。

TiNKは、他社のパートナーサービスとの連携も見据えていますが、そのときにも、Open APIに準拠して作っていることが役立ちます。Open APIに準じたYAMLファイルからは、ドキュメントを自動生成できるので、わざわざ仕様などをドキュメント化する必要がありません。

そしてもちろん、YAMLファイルをそのままパートナーに渡せれば、バートナーは、Swagger(もしくはそれに準じた他の自動生成ツール)を使うことで、そのYAMLファイルから、サーバーAPIを実行するためのプログラムを自動的に生成することさえできるのです。

近年のシステムは、サーバーとクライアントが分離して、それが複雑に絡み合っています。
これらのやりとりの方法を標準的な記法で記述するためのOpenAPI、そして、それを支えるツールであるSwaggerは、サーバーとクライアントの、さまざまな組み合わせを実現するための基礎技術として、今後、欠かせないものとなるでしょう。

文:大澤文孝

テクニカル・ライター、プログラマー/システムエンジニア。情報セキュリティスペシャリスト、ネットワークスペシャリスト。入門書からプログラミングの専門書まで幅広く執筆。主な入門書に「ちゃんと使える力を身につける Webとプログラミングのきほんのきほん」(マイナビ)、「いちばんやさしいPython入門教室」(ソーテック社)、「プログラムのつくり方」(工学社)などがある。趣味は作曲。Apple MusicやAmazon Musicなどでデバッグ音頭を配信中。

株式会社 tsumug | 〒810-0041 福岡市中央区大名 2 丁目 6-11 FUKUOKA growth next 301