RESTful APIについて
RESTful API（Representational State Transferful Application Programming Interface）は、Webアプリケーションやサービスを開発するためのアーキテクチャスタイルの一つです。REST（Representational State Transfer）は、分散システムのアーキテクチャスタイルの一つであり、HTTPプロトコルを使用してクライアントとサーバー間の通信を行います。RESTful APIは、このRESTの原則に基づいて設計されたAPIのことを指します。
RESTful APIは現在一番汎用されているAPIのタイプになり、ソフト開発のプロセス中に、RESTful APIを設計したりする必要がある場合がよくあります。本文では、RESTful API設計の基本原則とポイントを紹介した上、Restful APIの設計方法もステップバイステップで詳しく解説します。
RESTful APIを設計する原則とポイント
RESTful APIは、RESTの原則に基づいて設計されるので、RESTful APIを設計するには、常に下記のステップが必要となります。
- APIのリソースの指定：APIのエンドポイントとなるURLとパスです。
- HTTPメソッドの選択：各リソースに対する具体的な操作（添削、変更、データ取得など）によってHTTPメソッドを指定します。
- APIの詳細説明の追加：このAPIの役割、使用方法及び注意事項などの情報を含む詳細説明を追加して、利用者がより正しくこのAPIを使用できます。
- レスポンスフォーマットを特定：リクエストに成功したレスポンスの例を指定します。
- エラーコードの指定：エラーが発生した場合、適切なエラーメッセージを設計します。エラーの種類と原因を明確にし、適切なエラーコードやメッセージを返す必要があります。
- バージョンコントロール：バージョンコントロール機能を導入することで、APIに何か変更点がある場合、すぐに特定できます。
- ドキュメンテーション：設計したAPIの仕様と使用方法などを明確にドキュメンテーションすることが必要です。
上記は、RESTful APIを設計するためのポイントになります。RESTful APIを分かりやすく設計するために、常に上記の手順が必要になります。
ApidogでRESTful APIを簡単に設計する
RESTful APIを設計するために、一番便利なツールはApidogになります。Apidogは、非常に優れていたAPI管理ツールとして、非常に直感的な操作で、RESTful APIを簡単に設計してくれます。次は、Apidogを使って、REST原則に従って、新しいAPIを設計する方法をステップバイステップで解説します。
RESTful APIの設計方法をよりよく理解するため、下記のボタンからApidogのウェブツールを利用して、次のガイドを参照しなら、実戦することができます。
ステップ⒈ APIリソースの指定
Apidogで新しいAPIの作成画面の一番上に、APIリソースを指定するボックスがあります。ここでAPIのエンドポイントとパスを入力することで、APIのリソースを指定することができます。
ステップ⒉HTTPメソッドの選択
APIのリソースを指定した後、HTTPメソッドを設定する必要があります。目的別で、HTTPメソッドは常に下記のいずれかを使う必要があります。
- GET（コンテンツを取得）
- POST（コンテンツを新規追加）
- PUT（既存コンテンツを変更）
- DELETE（コンテンツを削除）
ステップ⒊APIの詳細説明を追加
ここでAPIの詳細説明を追加します。例えば、このAPIの役割、使用方法及び注意事項など、APIの取扱説明書のようなものを追加すると、利用者がより正しくこのAPIを使用できます。
ここで必須なRequestのパラメータ、Responseのパラメータを説明すると、API利用者がどのようにリクエストを送信するかをよりよく理解できます。
ApidogでAPIの説明文を追加する時に、Markdownフォーマットがサポートされます。
ステップ⒋レスポンスフォーマットを特定
そして、リクエストが成功に送信した時（HTTPステータスが200になるのは一般）のレスポンス例を追加します。このレスポンス例を追加すると、APIの利用者がリクエストの送信によって取得されたレスポンスをレスポンス例に比較して、操作が正確なのかを判断できます。
ステップ⒌エラーコードの指定
一般的には、APIのリクエストを成功に送信した場合、HTTPステータスが200になるのは一般的です。それ以外のHTTPステータスはエラーになると認識されます。
200以外のHTTPステータスコードは、APIのエラーコードになります。エラーコードは問題の原因を明確に示し、開発者がより早く診断し、問題を解決できる解決策とアドバイスを提供するべきです。API仕様書でよく設計されたエラーコードがあることは、APIの使いやすさと信頼性を高め、開発者は故障排除に要する時間を減らすことができます。
ApidogでResponseの部分で、「＋追加」ボタンをクリックして、エラーコードの例示を追加することができます。そして、Responseの例では、そのエラーコードに対応するレスポンスの例を追加することもできます。
参考のため、次は通用されているAPIエラーコード及びそのタイプを紹介します：
クライアントエラー：クライアントエラーは通常、クライアントが送信したリクエストに問題があることを意味します。例えば、パラメータの欠如、フォーマットエラー、権限不足などです。一般的なクライアントエラーコードには、400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Foundなどがあります。
サーバーエラー：サーバーエラーは通常、APIサーバーに問題があることを意味します。例えば、サーバー内部エラー、データベースの接続エラー、タイムアウトなどです。一般的なサーバーエラーコードには、500 Internal Server Error、502 Bad Gateway、503 Service Unavailableなどが含まれます。
業務エラー：業務エラーは通常、APIがクライアントリクエストを完了できないことを意味します。要求データが業務規則に合わなかったり、APIが要求を処理できないからです。一般的な業務エラーコードには422 Unprocessable Entity、429 Too Many Requests、451 Unavailable For Legal Reasonsなどがあります。
認証とセキュリティエラー：認証とセキュリティエラーは通常、APIがクライアントの身分を検証する必要があるが、認証できないか、認証が失敗することを意味する。一般的な認証とセキュリティエラーコードには、401 Unauthorized、403 Forbidden、419 Authentication Timeout、498 Invalid Tokenなどがあります。
制限と割当量エラー：制限と割当量エラーは通常、APIが特定の制限や割当量を超えたことを意味します。例えば、要求速度が制限を超えたり、割当量を超えたりします。一般的な制限と割当エラーコードには、429 Too Many Requests、503 Service Unavailable、509 Bandwidth Limit Exceededなどがあります。
ステップ⒍バージョンコントロール
APIを修正したり、変更したりする可能性があります。例えば、パラメータを追加したり、削除したり、変更したり、返すレスポンスのフォーマットを変更したりすることがよくあります。API仕様書にバージョンのコントロール機能がない場合、これら新しい変更はAPI利用者に迷惑をかけ、彼らの使用体験に悪影響を及ぼす可能性があります。
Apidogではバージョンコントロール機能も備えており、異なるバージョンのAPIの差分比較が行われ、開発者は需要に応じて異なるバージョンを選択できますし、各バージョンの違いと変更をいち早く把握することもできます。
ステップ⒎ドキュメンテーション化
ApidogでAPIを設計する場合、その以外の記録とドキュメンテーション化の操作を必要としません。上記のステップで定義したものを自動的に記録して、分かりやすいAPIの仕様書を生成するので、この仕様書を他のメンバーに共有することも便利です。
