REST API入門｜初心者にも分かりやすいREST APIガイド

RESTは最も主流のWebサービスやアプリケーションの設計思想になります。本文では、REST APIの特徴、設計原則、仕組みなどを皆さんに解説していきたいと思います。APIの初心者にも分かりやすいガイドなので、REST API入門のナレッジベースとして捉えることが可能です。

RESTとREST APIについて

RESTとREST APIは非常に密接な概念として、別々に紹介してはいけないと思いますので、本文で一番先にこの2つの概念を解説していこうと思います。

RESTとは

REST（Representational State Transfer）は、Webアーキテクチャのスタイルの1つであり、Web上でリソースを表現し、アクセスするための設計原則の集合体です。RESTは、HTTPプロトコルに基づいており、Webの性質に合わせたシンプルな設計が特徴です。

RESTは、クライアントとサーバーの間でデータをやり取りするための一連の原則を定義しています。RESTには、リソースの識別、リソースの表現、ステートレスな通信、キャッシュの利用、統一インターフェースなどが含まれます。

例えば、Webサイトにアクセスする場合、WebブラウザからWebサーバーにHTTPリクエストを送信し、WebサーバーからHTTPレスポンスを受け取ります。このような通信の場合、RESTの原則が適用されています。

REST APIとは

そもそもREST APIの概念については、RESTの概念とAPIの概念を組み合わせて理解すれば良いのです。

REST（Representational State Transfer）APIとは、Webアプリケーションの機能を外部のクライアントアプリケーションから利用するためのAPIの一種です。REST APIは、HTTPプロトコルを使用して通信を行い、一般的にJSONまたはXML形式でデータをやりとりします。

REST APIでは、リソース（データ）を一意の識別子（URI）で指定し、HTTPメソッド（GET、POST、PUT、DELETEなど）を使用してリソースを操作します。クライアントアプリケーションはHTTPリクエストを送信し、サーバーからのHTTPレスポンスを受け取ります。これにより、Webアプリケーションの機能を外部から利用することができます。

REST APIは、シンプルで拡張性が高く、複雑なシステムでも使用されることが多いため、Webアプリケーションの開発に欠かせない技術となっています。

また、ネットでREST APIとRESTful APIをよく目にすることがありますが、API初心者はこの2つの概念について疑問があるかもしれませんので、この2つの概念を解明するには、次の記事を参照してください。

REST APIの仕組み

REST APIはHTTPという既存の標準プロトコルを活用し、クライアント・サーバ間でリソースの状態を転送するというシンプルな構造を実現しています。

クライアントはHTTPプロトコルを利用して、サーバーの特定のURIにリクエストを送信する。
サーバーは、そのURIとHTTPメソッドから、クライアントが要求しているリソースとアクションを特定する。
サーバーは、要求に応じて適切な処理を実行する。データベースにアクセスして新規リソースの作成や、既存リソースの参照や更新などを行う。
処理結果を適切な形式で序列化し、HTTPレスポンスとしてクライアントに返送する。
クライアントはレスポンスを受信し、ステータスコードや本文を解析することで、要求した処理の結果を取得する。
必要に応じて、クライアントは追加のリクエストを新たに送信し、サーバーとやり取りを続ける。

4つのREST APIの設計規則

一般的には、REST設計思想には4つの主な設計原則があります。次は、これら4つの設計原則を1つずつ詳しく解説していこうと思います。

アドレス可能性

これはURIを使ってリソースに対して一意のアドレスを割り当てることを意味します。例えば、https://api.example.com/users/12345のように、ユーザーを表すリソースに一意のIDを含んだURIを割り当てることができます。アドレス可能性によって、リソースを参照および操作するための手段が提供されます。

統一したインターフェース

RESTではHTTPプロトコルという標準化されたインターフェースを使うことで、アプリケーション間での相互運用性を高めます。HTTPメソッドの使い分け(GET、POST、PUT、DELETEなど)によって、共通したインターフェースでさまざまな操作を実現できます。

ステートレス状態

これはサーバがクライアントのコンテキストや状態を保持しないことを意味します。したがってクライアントはリクエストごとに完全な情報を送信する必要があり、セッションIDやログイン状態などはクライアント側で管理します。これによりサーバのスケーラビリティが向上します。

接続性

これはクライアントとサーバが論理的に通信可能である必要があるということです。RESTではインターネット上の接続を利用するので、高い接続性を実現できます。

このようなREST APIの設計原則に基づくことで、拡張性と柔軟性に富んだウェブスケールのアーキテクチャを構築することができます。

REST APIの通信プロトコル

REST APIの通信に利用される主なプロトコルHTTPやHTTPSです。そこで、APIに対してCRUD操作を行うためのGET、POST、PUT、DELETEなどもHTTPメソッドと言えます。

また、すべてのREST APIもHTTPという通信プロトコルを使用していますので、多くのユーザーは、REST APIをHTTP APIとして捉えています。それは誤解です。REST APIは、RESTアーキテクチャの設計原則に基づいて設計されたHTTP APIのみを指しています。つまり、つまり、すべてのREST APIはHTTP APIであるが、すべてのHTTP APIがREST APIとは限らない、という関係です。

REST APIのクライアントサイドとサーバーサイド

完全なREST APIは、クライアントサイドとサーバーサイドを含みます。

クライアントサイド（フロントエンド）

REST APIのクライアントサイドは、主に次のような役割を果たしています。

APIのリクエストを作成し送信する
レスポンスを受信し解析する
データを表示したり保存したりする
ユーザインターフェースを提供する

サーバーサイド（バックエンド）

リクエストを受信し解析する
データベースにアクセスしデータを取得する
ビジネスロジックを実行する
適切なレスポンスを作成し返送する
セキュリティ、認証、認可を管理する
適切なHTTPステータスコードを返す

このように、概ねクライアントはリクエストの送信とレスポンスの処理を、サーバーはデータとビジネスロジックの処理をそれぞれ担当します。アプリケーション要件に応じて柔軟な実装が可能です。

Web開発やAPIのクライアントサイドとサーバーサイドについてより詳しく知りたい場合は、次の記事を参照してください：

Apidogを活用したREST APIの設計

REST APIを設計するために、一番便利なツールはApidogになります。Apidogは、非常に優れていたAPI管理ツールとして、非常に直感的な操作で、REST APIを簡単に設計してくれます。次は、Apidogを使って、REST原則に従って、新しいAPIを設計する方法をステップバイステップで解説します。

button

ステップ⒈ APIリソースの指定

ステップ⒉HTTPメソッドの選択

ステップ⒊APIの詳細説明を追加

ステップ⒋レスポンスフォーマットを特定

ステップ⒌エラーコードの指定

ステップ⒍バージョンコントロール

ステップ⒎ドキュメンテーション化

上記のように、ApidogというAPI設計ツールを使用すること、非常に直感的なGUIでREST APIを設計することもできます。設計が完了すると、非常に読みやすいAPIドキュメントを生成して他のチームメンバーに共有したりすることもできますので、非常に便利です。

button

REST APIのサーバーサイドの実装

REST API設計が完了する場合、Django REST framework、Flask RESTfulなどのフレームワークでサーバーサイドの実装が必要となります。REST APIの実装方法として、主に以下の2つのアプローチがあります。

一般的なウェブアプリケーションフレームワークを使う(Django、Flask等)
専用のREST APIフレームワークを使う(Django REST framework、Flask RESTful等)

後者のREST API専用フレームワークの方が、CRUD操作の実装やリクエスト/レスポンスの処理がライブラリレベルでサポートされているので、比較的容易にREST APIサーバーを構築できます。

したがって、可能であればDjango REST frameworkやFlask RESTfulといったフレームワークを使ってREST APIサーバーを実装することをおすすめします。

button

Apidogでサーバーサイドの実装コードを生成

バックエンド開発者がREST APIの設計書に従って、サーバーサイドの実装コードを手動で書く代わりに、Apidogという便利なAPI管理ツールを使って、API仕様に従って、1クリックで様々な言語やフレームワークのサーバーサイド実装コードを生成することができます。

ApidogのAPIドキュメントのページで「コード生成」→「サーバースタブとクライアントSDKを生成」の順にクリックして、様々な言語での数百個のフレームワークのサーバーサイドの実装コードを生成することができます。

ApidogでREST APIを簡単に利用可能

REST APIのサーバーサイドの実装が完了したら、次はクライアントサイドからそのAPIを利用するための実装を行うことができます。クライアントサイドからAPIを利用するには、様々なツールが利用できます。例えば、fetch APIやAxiosなどのライブラリを使ってHTTPリクエストを送信したり、cURLなどのコマンドベースのツールで利用したり、GUIツールのApidogやPostmanでリクエストの送信やレスポンスの確認を行なったりすることができます。

button

ここで最も使いやすいクライアントツールのApidogを利用してREST APIの利用手順を紹介していこうと思います。

APIの仕様書を参照して、当該APIの詳しい情報を手に入れた上、下記画像のように非常に直感的なUIで、APIリクエストを作成して、必要な情報（メソッド、URI、必須のパラメータなど）を記入して、リクエストを「送信」できます。

Apidogは非常に直感的なAPI利用方法を提供していますが、成功にAPIを利用するには、API仕様書に厳格に参照する必要があります。特にAPI仕様書に記載されている次の内容が間違わないように注意を払う必要があります。

利用可能なエンドポイントの一覧
各エンドポイントの詳細な利用方法
リクエストのパラメータやボディの指定の仕方
レスポンスのデータ構造やステータスコード
レート制限や認証の仕様

したがって、Apidogという便利なツールを活用しつつ、併せて仕様書をしっかり確認しながらAPI利用を進めましょう。

button

まとめ

この記事は、REST APIの基本的な概念や設計原則、実装方法、利用方法について解説しました。REST APIはHTTPをベースとしたAPI設計スタイルで、URIやHTTPメソッドを活用してリソース操作を実現する点が特徴です。記事ではRESTの定義や設計原則、APIの仕組みといった基礎概念から、実装時のフレームワークの選択、Apidogを用いた設計・利用方法まで、REST API導入の一連の流れを丁寧に解説しました。

また、記事のまとめとして、REST APIは拡張性と柔軟性に優れたアーキテクチャである一方、適切に設計・実装しないと期待した効果が得られない点に注意が必要になるのでしょう。Apidogといったツールを活用することで比較的容易に設計から運用までを行えるため、REST API入門には適した便利なツールになります。