Web APIという言葉はあちこちで耳にされることがあると思います。API＝アプリケーション・プログラミング・インターフェイス、ということで、つまり何かを作ったり動かしたりする時にやりとりをする機能、をWebで使えるようにしたもの、と考えておけばいいでしょうかね。Webブラウザの裏側でサーバ同士でデータをやりとりできるというのが肝で、各所のデータを統合した便利な機能を提供してくれたりするのはまさにWeb APIの恩恵によるものです。
世はWeb API花盛りです。花盛り過ぎて、それについて話題にすることもあまりなくなってきてはや10年、といったところです。あってもなくても、それはそれぞれのポリシーによる選択の結果をあらわしているに過ぎない、というところまで時代は進んでいるのかなと思っております。
しかしながら、一方で、開発途中のシステムだと、「Web APIも用意したけどあとまわし」ということも散見されます。また、Web APIを用意しても、「どういう構造になっているのか」「どういう風に使えるのか」を知らしめる仕様書のようなものが公開されていないと、せっかく用意したのにあまり使ってもらえないということもあります。逆に、あまり広く使われすぎると困るので仕様書は広く公開しないようにしていることもあるようです。
前置きが長くなりましたが、前回記事で紹介した「みんなで翻刻⇔みんなで検索」が実現できたのも、このWeb APIのおかげです。開発者である橋本雄太氏が、ご多忙な中で1時間でささっと作ってくださいました。ここでのWeb APIはそれほど複雑なものではなく、しかし、本文検索サイトを構築しつつ本家に更新があったらそれを検知して検索インデックスを更新する、という仕組みを作成するにあたって必要となる機能を大体網羅しているものでした。
というわけで、今回は、みんなで翻刻Web APIの紹介を少しだけ試みます。
まず、「現在登録されているプロジェクトの一覧」を取得するWeb API （のURL）は下記の通りです。
https://us-central1-honkoku2.cloudfunctions.net/api/projects
こちらにアクセスすると、プロジェクトの一覧とそれぞれの説明等に加えて、プロジェクトのIDが返戻されます。このフォーマットはWebでよく用いられるJSONというフォーマットになっています。これは、このまま見てもごちゃっとしてよくわかりませんが、全部コピペしてJSON整形ツールにかけると、構造を反映した形で見やすく表示できます。たとえばこのサイトだと以下のような感じになります。
つまり、「みんなで翻刻（以下、「みん翻」と略します）」で現在展開されているプロジェクトの情報を得たければ、このWeb APIで取得できる、ということになります。
さて、筆者が今回作ったのは「本文検索」でした。そうすると、ここで取得できる情報だけでは検索ができません。「みん翻」のデータは、
プロジェクト＞コレクション＞エントリ＞各頁（画像）
という風になっているようですので、次に、個々のプロジェクトが持っている「コレクション」の情報を取得します。この際には、上記のWeb APIで得られる各プロジェクトの"id"が必要になります。 これを何らかの方法で取得して、今度は以下のURLにてアクセスします。たとえば、「日本の仏典を翻刻！」のプロジェクトの場合、idは「21dzk」ですので、URLの最後に以下のようにそのプロジェクトidを付与してアクセスします。
https://us-central1-honkoku2.cloudfunctions.net/api/projects/21dzk
そうすると、このプロジェクトがどういうコレクションを持っているかという情報が得られます。これもやはり、先ほどと同じJSON形式で返戻されます。コレクションにはその説明もありますが、今回必要なのは本文ですので、さらに下の階層へと向かいます。このコレクションに含まれる（＝下位にある）エントリを取得すべく、とりあえずここで入手できたコレクションのidを用いて以下のようにWeb APIにアクセスしてみます。ちなみに、以下のURL中の「2AC632E5683C37F7C69425EA497007FA」という箇所が、上記のURLから得られたコレクションのidです。
https://us-central1-honkoku2.cloudfunctions.net/api/collections/2AC632E5683C37F7C69425EA497007FA
このURLにアクセスして返戻されたJSONデータを整形すると以下のようになります。
ここで、"entries": となっているキーの値が複数で列挙されています。これらの値がそれぞれのエントリのidということになります。この中の一つのエントリidを使って以下のURLを作ってアクセスしてみます。
https://us-central1-honkoku2.cloudfunctions.net/api/entries/6AC3A275993D8AC73941D97376426A61
ここでは、「6AC3A275993D8AC73941D97376426A61」がエントリidの部分になります。
このURLにアクセスすると、このエントリに含まれる画像とそれに対応する翻刻テキストのデータが入手できます。あとは、このテキストデータを検索できるようにして、画像ともリンクできるようにすればOKです。ちなみに、翻刻テキストデータは"transcriptions"以下にリストとして入っていて、各リストは辞書になっていて、その中の「text」というキーが翻刻テキストデータのようです。また、更新日付のキーは「timestamp」、といった案配です。画像に関しては、IIIF対応画像の翻刻をシステムの基盤の一つとしていることもあるのかもしれませんが、IIIF Manifestを継承した形になっているようで、これをきちんと理解しようと思うなら、IIIF Presentation API 2.1をみておくとよいかもしれません。
というわけで、今回は、Web APIで本文を取得する方法を最短距離でまとめてみました。
エントリのJSONデータからどのデータを取り出してどのように使ったか、という話は、また次の機会としましょう。
