原文: REST API Best Practices – REST Endpoint Design Examples
Web 開発において REST API は、クライアント・サーバー間のコミュニケーションをスムーズにする重要な役割を担っています。
クライアントはフロントエンド、サーバーはバックエンドと考えて構いません。
クライアント (フロントエンド) とサーバー (バックエンド) は通常、直接やりとりすることができません。そこで仲介役として Application Programming Interface (API) というインターフェイスが使われます。
このようにクライアント・サーバー間の通信においては API が極めて重要であることから、API を設計する際には常にベストプラクティスを念頭におくべきでしょう。そうすることで開発者がその API を保守、あるいは利用する際に、問題が生じることなく作業できるようになります。
この記事では、REST API を開発する際の 9 つのベストプラクティスを紹介します。API の利用者にとっても使いやすい、ベストな API を作成する助けとなれば幸いです。
そもそも REST API とは？
REST とは Representational State Transfer の略です。ウェブ向けのアーキテクチャ設計の指針として 2000 年に Roy Fielding によって考案された、ソフトウェアアーキテクチャのスタイルです。
REST の設計原則に従っている API は「RESTful」であると言います。
簡単に言えば、REST API は 2 台のコンピューターが HTTP (Hypertext Transfer Protocol) を介して通信するための手段です。クライアントとサーバーも HTTP で通信します。
REST API 設計のベストプラクティス
1. データの送受信には JSON 形式を使う
かつては API リクエストの受付および返答は主に XML 形式で行われ、HTML が用いられることさえもありました。しかし現在では、API データの送受信に広く使われているデファクトスタンダードは JSON (JavaScript Object Notation) 形式となっています。
例えば XML を用いる場合、データのデコードとエンコードが少し煩雑になることが多いため、現在では XML をサポートするフレームワークは少なくなりました。
JSON は元々この使い道が想定されているため、例えば JavaScript なら、fetch API を通して JSON データを構文解析する組み込みメソッドがあります。Python や PHP など他のプログラミング言語を使う場合でも、それぞれの言語に JSON データを解析したり操作したりするメソッドがあります。
例えば Python では JSON データを扱うために json.loads() や json.dumps() というメソッドが提供されています。
そしてクライアントが正しく JSON データを解釈できるようにするためには、リクエストに対するレスポンスヘッダーの Content-Type を application/json に設定します。
一方、サーバーサイドフレームワークの多くは Content-Type を自動で JSON に定めます。例えば Express の場合、現在では express.json() ミドルウェアがこの目的で使われます。NPM パッケージ body-parser も同じように使われます。
2. エンドポイントには動詞ではなく名詞を使う
REST API を設計する際、エンドポイントのパスには動詞を使わない方が良いでしょう。エンドポイントには各エンドポイントの機能を表す名詞を使います。
この理由は、GET、POST、PUT、PATCH、DELETE など基本の CRUD (Create, Read, Update, Delete) 操作を行うための HTTP メソッドで既に動詞が使われているからです。
GET、POST、PUT、PATCH、DELETE は最もよく使われる HTTP メソッドです。他には COPY、PURGE、LINK、UNLINK などもあります。
つまり、エンドポイントは例えば https://mysite.com/getPosts や https://mysite.com/createPost のような形ではなく、https://mysite.com/posts のような形にすべきです。
まとめると、エンドポイントが実行する操作は HTTP メソッドの動詞で表現しましょう。GET ならばデータを取得する、POST ならばデータを作成する、PUT ならばデータを更新する、DELETE ならばデータを削除するというようにです。
3. コレクションは名詞の複数形で命名する
あなたの API のデータを、API の利用者が入力したさまざまなリソースの集まり (コレクション) だと考えてみましょう。
もし https://mysite.com/post/123 というエンドポイントがある場合、DELETE リクエストで投稿 (post) を削除したり PUT または PATCH リクエストで投稿を更新したりする分には問題ないかもしれませんが、コレクションの中に他の投稿があるかもしれないことがユーザーに伝わりません。これがコレクションには複数形の名詞を使うべき理由です。
つまり、https://mysite.com/post/123 ではなく https://mysite.com/posts/123 とすると良いでしょう。
4. エラーハンドリングにはステータスコードを使う
API へのリクエストに対する返答では常に、規定に従った HTTP ステータスコードを使うべきです。これにより API のユーザーは何が起きているか、リクエストが成功したのか、失敗したのか、何か他の状況かなどを知ることができます。
以下は各 HTTP ステータスコードの範囲とその意味の表です。
| ステータスコードの範囲 | 意味 |
|---|---|
| 100 – 199 | 情報レスポンス 例えば 102 はリソースが処理中であることを表す。 |
| 300 – 399 | リダイレクト 例えば 301 は「Moved Permanently」(リソースが恒久的に移動されたこと) を意味する。 |
| 400 – 499 | クライアント側エラー 400 は「Bad Request」(リクエストに問題があること)、404 は「Not Found」(リソースが見つからなかったこと) を意味する。 |
| 500 – 599 | サーバー側エラー 例えば 500 は「Internal Server Error」(サーバー側でエラーが発生したこと) を意味する。 |
5. 関係を表すにはエンドポイントのネストを使用する
しばしば、異なるエンドポイントが関係している場合があります。そのような場合にはエンドポイントをネストして関係をわかりやすくしましょう。
例えば複数のユーザーが利用するブログプラットフォームのようなケースでは、異なる投稿 (post) はそれぞれ異なる著者 (author) によって書かれている可能性があります。そのような場合は https://mysite.com/posts/author のようなエンドポイントがネストの仕方として適切でしょう。
同様に、投稿にはそれぞれコメントがあるかもしれません。コメントのリストを取得するには https://mysite.com/posts/postId/comments のようなエンドポイントが理にかなっているでしょう。
ただし深さが 3 段階を超えるようなネストは、API が複雑になり読みづらくなるため避けた方がいいでしょう。
6. 要求されたデータの取得にフィルター、ソート、ページネーションを活用する
時には API のデータベースが非常に大きくなることもあります。そのようなデータベースからのデータの取得にはとても時間がかかる可能性があります。
フィルター、ソート、ページネーションは、REST API のコレクションに対して実行可能な操作です。このような操作によって、必要なデータのみを取得、並べ替え、ページを分けるなどして、サーバーがリクエストの処理で占有されすぎないようにすることが可能です。
フィルターを適用したエンドポイントの例は次の通りです:https://mysite.com/posts?tags=javascript
このエンドポイントでは「JavaScript」というタグが付けられた投稿を取得します。
7. セキュリティのため SSL を使用する
SSL とは Secure Socket Layer の略です。SSL は REST API 設計のセキュリティ面で非常に重要です。SSL は API の安全性を高め、悪意のある攻撃を受けにくくします。
その他考慮すべきセキュリティ対策としては、サーバーとクライアント間の通信をプライベートにすること、API の利用者がリクエストした以上のものを取得できてしまわないようにすることなどが含まれます。
SSL 証明書のサーバーへの設定は難しくなく、最初の一年間無料で利用できる証明書などもあります。有料の場合も、高額なものではありません。
SSL を使用している REST API とそうでないものの明確な違いは、URL の HTTP に「s」が付いているかどうかです:https://mysite.com/posts は SSL を使用しています。http://mysite.com/posts は SSL を使用していません。
8. バージョンを明確にする
クライアント (ユーザー) を強制的に新しいバージョンへ移行させることのないように、REST API では複数のバージョンを利用できるようにしましょう。新バージョンへの移行は、注意深く行わなければアプリケーションが壊れる可能性がある作業です。
ウェブ開発で最も一般的なバージョニングシステムの 1 つがセマンティックバージョニングです。
セマンティックバージョニングのバージョン番号は、1.0.0 や 2.1.2、あるいは 3.3.4 のようになります。最初の数字はメジャーバージョン、二番目の数字はマイナーバージョン、三番目はパッチバージョンを表します。
大規模なテック企業の RESTful API も、個人開発の場合も、次のような形式がよく使われます:https://mysite.com/v1/ がバージョン 1https://mysite.com/v2 がバージョン 2
Facebook API では次のようにバージョン番号が付けられています。
Spotify でも同様のバージョン番号が付けられています。
すべての API がこの通りではありません。Mailchimp の API では異なる形式が使われています。
このような形で REST API を公開することにより、クライアントが新しいバージョンに移行しないことを選択した場合には移行を強制しないようにできます。
9. 正確な API ドキュメントを提供する
REST API を作成する際には、クライアント (利用者) が正しい使い方を学習、理解できるようにする必要があります。ベストな方法は良い API ドキュメントを提供することです。
ドキュメントには次の情報を含めましょう。
- API の適切なエンドポイント
- エンドポイントに対するリクエスト例
- いくつかのプログラミング言語での実装例
- 各種エラーのエラーメッセージとステータスコードのリスト
API ドキュメントの作成によく使われるツールの 1 つに Swagger があります。ソフトウェア開発で API テストツールとして使われることの多い Postman も、API ドキュメントの作成にも利用できます。
結論
この記事では、REST API の開発時に心に留めておくべきベストプラクティスについて学びました。
これらのベストプラクティスや慣習を実践することが重要です。そうすることで、スムーズに機能し、安全で、API 利用者にとって使いやすいアプリケーションを開発できるでしょう。
お読みいただきありがとうございました。早速この記事で学んだベストプラクティスを活かした API を作成してみましょう。