解説：Web APIとは、それを設計する方法は？

近年、Web APIは非常に話題になっています。それでは、Web APIとはなんですか？どうやってWeb APIを構築して仕事の効率化を図ればいいですか？本文では、これらの問題を解明していきます。

Web APIとは

そもそもWeb APIとはなんですか？Web APIという名前から見ると、それはAPIの一種になりますね。実際には、現在の業界では、Web APIに関して、厳格な定義がありません。Web APIは、HTTPというプロトコルを利用するAPIを指すこともありますし、Webサーバー、Webブラウザで利用されているAPIのみを指すこともあります。

Web APIの主な種類

以上の定義から派生すると、Web APIの種類は主に次のようになります。

REST API

Web APIといえば、最も多くの場合はREST APIを指しています。HTTPプロトコルを使用するAPIの中で、現在REST APIは一番汎用されている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アプリケーションの機能を外部から利用することができます。

SOAP API

SOAP（Simple Object Access Protocol）は、ウェブサービス間での情報交換を目的とした通信プロトコルです。SOAPはXML（eXtensible Markup Language）ベースのプロトコルであり、クライアントとサーバー間でメッセージをやり取りするためのルールや形式を提供します。また、SOAP APIは、異なるプラットフォームやプログラミング言語間での相互運用性を提供するために広く使用され、セキュリティやトランザクション管理などの機能もサポートできるので、信頼性の高いウェブサービス通信を実現することもできます。

XML-RPC

XML-RPC（Extensible Markup Language Remote Procedure Call）は、リモートプロシージャコール（RPC）プロトコルの一種です。XML-RPCでは、データをXML形式でエンコードするため、さまざまなプログラミング言語やプラットフォームで利用することができます。メソッドの呼び出しやデータの受け渡しにおいて、独自の通信プロトコルを実装する必要がなくなります。そのため、異なるシステム間での相互運用性を高めるのに役立ちます。

JSON-RPC

JSON-RPC（JavaScript Object Notation Remote Procedure Call）は、JSON形式を使用してリモートプロシージャコール（RPC）を行うためのプロトコルです。JSON-RPCは、JSONデータ形式が広くサポートされているため、さまざまなプログラミング言語やプラットフォームで利用することができます。また、シンプルな構造と軽量なデータサイズが特徴であり、利用しやすさと効率性を両立しています。

上記で紹介したいずれかの種類ともWeb APIだと言えます。そこで、誰かにWeb APIと言われると、REST APIを指す可能性が一番高くなると思いますが、直接にそれをREST APIだと認識することができません。

Web APIの設計：どの種類にも完璧に互換できるApidog

Apidogは非常に強力的なAPI管理ツールになります。Apidogを使用することで、Web APIにリクエストを送信してレスポンスを取得したり、どの種類のWeb API（REST、SOAP、JSON-RPC、XML-RPCなど）を設計したりすることもできます。次は、一番汎用されているREST APIの作成方法を例にして皆さんに紹介します。

Web APIの設計方法をよりよく理解するために、次のボタンをクリックして、Apidogのオンラインバージョンを利用して、次のステップに従って操作することをお勧めします。

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

Apidogで新しいAPIの作成画面の一番上に、APIリソースを指定するボックスがあります。ここでAPIのエンドポイントとパスを入力することで、APIのリソースを指定することができます。

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

APIのリソースを指定した後、HTTPメソッドを設定する必要があります。どちらのWeb APIもHTTPプロトコルを使用していますので、目的別で、HTTPメソッドを選択する必要があります。HTTPメソッドといえば、常に下記のものがあります。

• GET（コンテンツを取得）
• POST（コンテンツを新規追加）
• PUT（既存コンテンツを変更）
• DELETE（コンテンツを削除）

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

ここでAPIの詳細説明を追加します。例えば、このAPIの役割、使用方法及び注意事項など、APIの取扱説明書のようなものを追加すると、利用者がより正しくこのAPIを使用できます。

ここで必須なRequestのパラメータ、Responseのパラメータを説明すると、API利用者がどのようにリクエストを送信するかをよりよく理解できます。ApidogでAPIの説明文を追加する時に、Markdownフォーマットがサポートされます。

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

そして、リクエストが成功に送信した時（HTTPステータスが200になるのは一般）のレスポンス例を追加します。このレスポンス例を追加すると、APIの利用者がリクエストの送信によって取得されたレスポンスをレスポンスの定義に比較して、自動的に正確なレスポンスを取得できるかを検証してくれます。

ステップ⒌スターテスコードの指定（RESTのみ）

一般的には、APIのリクエストを成功に送信した場合、HTTPステータスが200になるのは一般的です。それ以外のHTTPステータスはエラーになると認識されます。ただし、各Web APIの規範では、REST APIの仕様でHTTPステータスコードの設定を要件にしています。他のAPIの仕様では、HTTPステータスコードの定義を必要な要件としていません。

200以外のHTTPステータスコードは、APIのエラーコードになります。エラーコードは問題の原因を明確に示し、開発者がより早く診断し、問題を解決できる解決策とアドバイスを提供するべきです。API仕様書でよく設計されたエラーコードがあることは、APIの使いやすさと信頼性を高め、開発者は故障排除に要する時間を減らすことができます。

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

APIを修正したり、変更したりする可能性があります。例えば、パラメータを追加したり、削除したり、変更したり、返すレスポンスのフォーマットを変更したりすることがよくあります。API仕様書にバージョンのコントロール機能がない場合、これら新しい変更はAPI利用者に迷惑をかけ、彼らの使用体験に悪影響を及ぼす可能性があります。

Apidogではバージョンコントロール機能も備えており、異なるバージョンのAPIの差分比較が行われ、開発者は需要に応じて異なるバージョンを選択できますし、各バージョンの違いと変更をいち早く把握することもできます。

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

ApidogでAPIを設計する場合、それ以外のドキュメンテーション化の操作を必要としません。上記のステップで定義したものを自動的に記録して、分かりやすいAPIの仕様書を生成するので、この仕様書を他のメンバーに即座に共有することができます。

まとめ

Web API設計において効率よく正確なドキュメント作成ができるApidogは、大きな強みがあります。ApidogはWeb API設計からドキュメント化までをサポートする手厚いツールであり、開発効率化に多大な貢献が期待できます。

Apidogなら、REST APIやSOAP、JSON-RPCなど、様々な種類のWeb APIをインタラクティブに定義できます。リソースの指定からレスポンス例の設定まで直感的な操作で実装が進められます。また、バージョン管理機能があるので、APIの変更履歴を管理しやすく、API利用者とのすり合わせもスムーズです。そして、デザインしたAPIは自動的にドキュメント化されるため、共有・公開できる状態の仕様書を手軽に作成できるのが大きなメリットです。