Zenn
🙆

APIを設計する上でおさえておきたい大原則

2022/09/13に公開
API
idea

はじめに

今回の記事で、初めてZennに投稿する。

現在、私たちプログラマーがAPIを開発しなければならない場面が多くなってきている。サービス同士の連携だけでなく、モバイルアプリケーションのバックエンドや、ゲームでもサーバーとの連携が増えてきている。さらに、Webアプリケーションの非同期通信にJSONが使われるケースも少なからず出てくる。今やAPIは、インターネットやWebに関連するソフトウェア開発者にとっては必須の分野と言っても過言ではない。

O'Reillyが出版した『Web API: The Good Parts』では、APIを設計する上で重要な考え方や具体的なテクニックが満載の一冊である。本書を通して、APIの基礎から応用まで幅広く学べる。API開発に携わる人なら、購入しておいて損はないだろう。

今回の記事では、『Web API: The Good Parts』の内容をベースに、APIを設計する上で押さえておきたい大原則を簡潔に解説する。

APIとは何か？

APIの定義は非常に曖昧だ。本書が主に対象とするAPIは、HTTPプロトコルを用いてネットワーク上で呼び出されるAPIである。HTTPプロトコルを使うので、エンドポイントはURIで指定する。簡単に言えば、APIとはURIのことである。

簡単に言うと、API(Application Programming Interface)とは、あるURIにアクセスすることで、サーバー側の情報を書き換えたり、サーバー側に置かれた情報を取り出したりできるWebシステムで、プログラムからアクセスして、そのデータを機械的に利用することを想定しているのである。APIは、ブラウザーを使って人間が直接アクセスすることを想定していない。

例えば、APIテスト用の無料Fake APIであるJSONPlaceholderを使った例を考えてみよう。まず、以下のURIにアクセスする。

https://jsonplaceholder.typicode.com/posts/1

上記のURIにアクセスしたあと、以下のような情報を取り出せる。

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\\nsuscipit recusandae consequuntur expedita et cum\\nreprehenderit molestiae ut ut quas totam\\nnostrum rerum est autem sunt rem eveniet architecto"
}

ここで注目するべきことは、この情報がブラウザでWebページを表示するためのHTMLではなくJSONと呼ばれる形式で表示されている点である。要は、このURIはブラウザ上で直接表示されることを想定していないのだ。

このように、APIは人間が直接アクセスして利用することを想定しておらず、主にプログラムがデータを取得して別の用途に利用するために設計されているのだ。

APIを公開するべき理由

あなたがすでにサービスを公開していると仮定する。まだインターネットにAPIを公開していないのであれば、すでに述べたようにAPIの公開を検討すべきだ。しかし、APIで何を公開すればいいのだろうか？

簡単に言うと、そのサービスができることは全てAPIでできるようにするべきだ。例えば、ECサイトであれば商品の検索・購入やレコメンド情報の取得、不動産検索サイトであれば物件の検索・絞り込みや間取り情報の取得がAPI経由でできるようにしておこう。

具体的には、サービスの核となる部分はすべてAPIで利用できるようにする。例えば、ECサイトであれば、商品の検索や購入がコアな機能となる。

APIを公開するリスク

まず前提として、自分のWebサービスが一般にあまり知られていないのであれば、APIを設計する必要はない。一方、自分のWebサービスが有名で人気がある場合、APIを公開すればより多くの人が注目するようになる。その場合、データが悪用されないか心配になるかもしれない。これは実は、運用方法に大きく依存する。

APIを公開するということは、プログラムによる無制限のアクセスを受け入れるということではない。

多くの場合、APIにはレートリミット、つまりユーザーごとのアクセス回数制限が設けられており、それを超える大量のアクセスがあった場合には料金が発生したり、そもそも一定以上のアクセスができないような仕組みになっている。例えば、Googleは検索機能や翻訳機能のサービスをAPIで公開しているものの、Googleの検索機能を使ってGoogleと同規模の検索エンジンを開発することは困難である。

第二の前提は、データを盗もうとする人は、APIの公開・非公開に関係なく情報を盗もうとすることだ。より具体的に言えば、HTMLページに機械的にアクセスして情報を抽出するウェブスクレイピングがある。これは、APIが公開されていない情報がどうしても欲しい開発者がよくやる方法だ。自分たちでAPIを管理しないと、情報の取得をコントロールできない状況に陥る可能性がある。

まとめ

今回の記事では、O'Reillyの技術書『Web API: The Good Parts』をベースに、以下の内容を簡単に解説した。

  • APIの概要
  • APIを設計することの重要性
  • APIで公開するべきもの
  • APIを公開することのリスク
GitHubで編集を提案

Discussion